/ Hex Artifact Content
Login

Artifact eea3f417059c203f450ec64acbb19e6201063c0c:


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 74 68  ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst 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 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
4090: 2c 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 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63  t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69  rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5950: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5970: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5990: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
59a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
59b0: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
5a20: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a60: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
5ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ae0: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
5af0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b00: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
5b10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
5b30: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
5b40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
5b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b70: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
5b80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b90: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5ba0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5bb0: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
5bc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5bd0: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
5be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5bf0: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
5c00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5c10: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
5c20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
5c40: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5c50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
5c60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c70: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5c80: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
5c90: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
5ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cb0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5cc0: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
5cd0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
5ce0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cf0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
5d00: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
5d10: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
5d20: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5d30: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5d40: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5d50: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5d60: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5d70: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5d80: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5d90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5da0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5db0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5dc0: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5dd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5df0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5e00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e10: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5e20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e30: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5e40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5e50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e60: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5e70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e80: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5e90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ea0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5eb0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5ec0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5ed0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5ee0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f00: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5f10: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5f20: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
5f30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
5f50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5f60: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5f70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f80: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5f90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5fa0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5fb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fc0: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5fd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5fe0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5ff0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6010: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6020: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6030: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6040: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6050: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6060: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
6070: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6080: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
60b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
60c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60e0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
60f0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6100: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6130: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6140: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
6170: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
6180: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6190: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61a0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
61b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
61c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61e0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
61f0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6200: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6210: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6220: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6230: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6240: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6250: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
6280: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
6290: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
62b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62c0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
62d0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
62e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6300: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6310: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6320: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6330: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6340: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6350: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6360: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
6370: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
6380: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6390: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
63c0: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
63d0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
63e0: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
63f0: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6400: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6410: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6420: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6430: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6440: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
6450: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
6460: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
6470: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
6480: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
6490: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
64a0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
64b0: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
64c0: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
64d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
64e0: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
64f0: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6500: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6510: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6520: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6530: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6540: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6550: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6560: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
6570: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
6580: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
6590: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
65a0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
65b0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
65c0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
65d0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
65e0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
65f0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6600: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6610: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6620: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6630: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6640: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6650: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6660: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
6670: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
6680: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
6690: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
66a0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
66b0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
66c0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
66d0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
66e0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
66f0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6700: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6710: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6720: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6730: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6740: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6750: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
6760: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
6770: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
6780: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
6790: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
67a0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
67b0: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
67c0: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
67d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
67e0: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
67f0: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6800: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6810: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6820: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6830: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6840: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
6850: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
6860: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6870: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
6880: 2a 2a 20 61 6e 64 20 53 51 4c 49 54 45 5f 49 4f  ** and SQLITE_IO
6890: 43 41 50 5f 55 4e 4d 4f 56 41 42 4c 45 5f 57 48  CAP_UNMOVABLE_WH
68a0: 45 4e 5f 4f 50 45 4e 20 66 6c 61 67 73 20 69 6e  EN_OPEN flags in
68b0: 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69  dicate that a fi
68c0: 6c 65 20 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  le .** cannot be
68d0: 20 64 65 6c 65 74 65 64 20 6f 72 20 72 65 6e 61   deleted or rena
68e0: 6d 65 64 20 77 68 65 6e 20 6f 70 65 6e 2c 20 72  med when open, r
68f0: 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2f 0a  espectively..*/.
6900: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6910: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6920: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6930: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6950: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6960: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6970: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6980: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
6990: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69a0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
69b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69c0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
69d0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
69e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69f0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
6a00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6a10: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
6a20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6a40: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
6a50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a60: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
6a70: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6a80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a90: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
6aa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ab0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
6ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ad0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
6ae0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
6af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b00: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6b10: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b20: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
6b30: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6b40: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
6b50: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
6b60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b70: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
6b80: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
6b90: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
6ba0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6bb0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
6bc0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
6bd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6be0: 55 4e 4d 4f 56 41 42 4c 45 5f 57 48 45 4e 5f 4f  UNMOVABLE_WHEN_O
6bf0: 50 45 4e 20 20 20 20 30 78 30 30 30 30 32 30 30  PEN    0x0000200
6c00: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
6c10: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
6c20: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  Levels.**.** SQL
6c30: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
6c40: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6c50: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6c60: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
6c70: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6c80: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6c90: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
6ca0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
6cb0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6cc0: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
6cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6ce0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
6cf0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
6d00: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
6d10: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6d20: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6d30: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
6d40: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
6d50: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
6d60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6d70: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6d80: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6d90: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
6da0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
6db0: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
6dc0: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
6dd0: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
6de0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
6df0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6e00: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
6e10: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
6e20: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6e30: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
6e40: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
6e50: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
6e60: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
6e70: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
6e80: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
6e90: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
6ea0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
6eb0: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
6ec0: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
6ed0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6ee0: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
6ef0: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65  hed. If the lowe
6f00: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74  r four bits of t
6f10: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c  he flag.** equal
6f20: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
6f30: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  MAL, that means 
6f40: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
6f50: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
6f60: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72  .** If the lower
6f70: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c   four bits equal
6f80: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6f90: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  L, that means.**
6fa0: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
6fb0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
6fc0: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
6fd0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74  ()..**.** Do not
6fe0: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c   confuse the SQL
6ff0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7000: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7010: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69  FULL flags.** wi
7020: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73  th the [PRAGMA s
7030: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d  ynchronous]=NORM
7040: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73  AL and [PRAGMA s
7050: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c  ynchronous]=FULL
7060: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54  .** settings.  T
7070: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20  he [synchronous 
7080: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e  pragma] determin
7090: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f  es when calls to
70a0: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46   the.** xSync VF
70b0: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61  S method occur a
70c0: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f  nd applies unifo
70d0: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  rmly across all 
70e0: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68  platforms..** Th
70f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7100: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7110: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20  SYNC_FULL flags 
7120: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a  determine how.**
7130: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69   energetic or ri
7140: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66  gorous or forcef
7150: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72  ul the sync oper
7160: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a  ations are and.*
7170: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69  * only make a di
7180: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20  fference on Mac 
7190: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61  OSX for the defa
71a0: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e  ult SQLite code.
71b0: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79  .** (Third-party
71c0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
71d0: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  ions might also 
71e0: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
71f0: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
7200: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7210: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7220: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f  NC_FULL, but amo
7230: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74  ng the.** operat
7240: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69  ing systems nati
7250: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62  vely supported b
7260: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d  y SQLite, only M
7270: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20  ac OSX.** cares 
7280: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72  about the differ
7290: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e  ence.).*/.#defin
72a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
72b0: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
72c0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
72d0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
72e0: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
72f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7300: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
7310: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
7320: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7330: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
7340: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20  Handle.**.** An 
7350: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7360: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
7370: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
7380: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
7390: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72  3_vfs | OS inter
73a0: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e  face layer].  In
73b0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
73c0: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  rface.** impleme
73d0: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
73e0: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
73f0: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
7400: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
7410: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
7420: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
7430: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
7440: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
7450: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
7460: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7470: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
7480: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
7490: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
74a0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
74b0: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
74c0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
74d0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
74e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
74f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
7500: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
7510: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7520: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
7530: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
7540: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
7550: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
7560: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7570: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
7580: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
7590: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
75a0: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
75b0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
75c0: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
75d0: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
75e0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
75f0: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
7600: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
7610: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7620: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
7630: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
7640: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
7650: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
7660: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
7670: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
7680: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
7690: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
76a0: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
76b0: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
76c0: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
76d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
76e0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
76f0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7700: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74  Open] method set
7710: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
7720: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
7730: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
7740: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
7750: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
7760: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
7770: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
7780: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
7790: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  if the [sqlite3_
77a0: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72  vfs.xOpen] repor
77b0: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
77c0: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
77d0: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
77e0: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
77f0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
7800: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  led [sqlite3_vfs
7810: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f  .xOpen].** is fo
7820: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r the [sqlite3_v
7830: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74  fs.xOpen] to set
7840: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
7850: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
7860: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  nt.** to NULL..*
7870: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
7880: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
7890: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
78a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
78b0: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
78c0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
78d0: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
78e0: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
78f0: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ync()..** The se
7900: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
7910: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
7920: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b  fullsync.  The [
7930: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7940: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61  ONLY].** flag ma
7950: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20  y be ORed in to 
7960: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
7970: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
7980: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e  he file.** and n
7990: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
79a0: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e  ds to be synced.
79b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67  .**.** The integ
79c0: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f  er values to xLo
79d0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
79e0: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a  () are one of.**
79f0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7a00: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
7a10: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7a20: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7a30: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7a40: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
7a50: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7a60: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7a70: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
7a80: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7a90: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
7aa0: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
7ab0: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
7ac0: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
7ad0: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20  he lock..** The 
7ae0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7af0: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63  ck() method chec
7b00: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64  ks whether any d
7b10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
7b20: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e  on,.** either in
7b30: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72   this process or
7b40: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
7b50: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
7b60: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a  ng a RESERVED,.*
7b70: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
7b80: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
7b90: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
7ba0: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
7bb0: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
7bc0: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74  sts and false ot
7bd0: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  herwise..**.** T
7be0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
7bf0: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
7c00: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
7c10: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
7c20: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
7c30: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
7c40: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
7c50: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
7c60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
7c70: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
7c80: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
7c90: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
7ca0: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
7cb0: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
7cc0: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
7cd0: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
7ce0: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64  pointer intended
7cf0: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20   to.** point to 
7d00: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  a structure that
7d10: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67   may contain arg
7d20: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20  uments or space 
7d30: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77  in which to.** w
7d40: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75  rite return valu
7d50: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75  es.  Potential u
7d60: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e  ses for xFileCon
7d70: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a  trol() might be.
7d80: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ** functions to 
7d90: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20  enable blocking 
7da0: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f  locks with timeo
7db0: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74  uts, to change t
7dc0: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74  he.** locking st
7dd0: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d  rategy (for exam
7de0: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66  ple to use dot-f
7df0: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69  ile locks), to i
7e00: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20  nquire.** about 
7e10: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20  the status of a 
7e20: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61  lock, or to brea
7e30: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20  k stale locks.  
7e40: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f  The SQLite.** co
7e50: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20  re reserves all 
7e60: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
7e70: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
7e80: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c  n use..** A [SQL
7e90: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
7ea0: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  ATE | list of op
7eb0: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
7ec0: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
7ed0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
7ee0: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
7ef0: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
7f00: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
7f10: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
7f20: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
7f30: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
7f40: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
7f50: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
7f60: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
7f70: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
7f80: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
7f90: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
7fa0: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
7fb0: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
7fc0: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
7fd0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
7fe0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
7ff0: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
8000: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
8010: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
8020: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
8030: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
8040: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
8050: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
8060: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
8070: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
8080: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
8090: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
80a0: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
80b0: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
80c0: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
80d0: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
80e0: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
80f0: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
8100: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8110: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
8120: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8130: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
8140: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8150: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
8160: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8170: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
8180: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8190: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
81a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
81b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
81c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
81d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
81e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
81f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
8200: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8210: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
8220: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8230: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8240: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
8250: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8260: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
8270: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
8280: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
8290: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
82a0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
82b0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
82c0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
82d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
82e0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
82f0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
8300: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
8310: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
8320: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
8330: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
8340: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
8350: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
8360: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
8370: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
8380: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8390: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
83a0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
83b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
83c0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
83d0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
83e0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
83f0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
8400: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
8410: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
8420: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
8430: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8440: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
8450: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
8460: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
8470: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
8480: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
8490: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
84a0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
84b0: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
84c0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
84d0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
84e0: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
84f0: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
8500: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
8510: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
8520: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
8530: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
8540: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8550: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
8560: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
8570: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
8580: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8590: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
85a0: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
85b0: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
85c0: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
85d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
85e0: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
85f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
8600: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8610: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
8620: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
8630: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
8640: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8650: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
8660: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
8670: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8680: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8690: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
86a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
86b0: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
86c0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
86d0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
86e0: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
86f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8700: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
8710: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
8720: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8730: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
8740: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
8750: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8760: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
8770: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
8780: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8790: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
87a0: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
87b0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
87c0: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
87d0: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
87e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
87f0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
8800: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
8810: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8820: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
8830: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
8840: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
8850: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8860: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8870: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
8880: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
8890: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
88a0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
88b0: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
88c0: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
88d0: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
88e0: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
88f0: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
8900: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
8910: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8920: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
8930: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
8940: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
8950: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
8960: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
8970: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
8980: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
8990: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
89a0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
89b0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
89c0: 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46   2 */.  int (*xF
89d0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
89e0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
89f0: 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41  64 iOfst, int iA
8a00: 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a  mt, void **pp);.
8a10: 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68    int (*xUnfetch
8a20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a30: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8a40: 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a  Ofst, void *p);.
8a50: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8a60: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8a70: 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20   version 3 */.  
8a80: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
8a90: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
8aa0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
8ab0: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
8ac0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
8ad0: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
8ae0: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a  ol Opcodes.**.**
8af0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
8b00: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
8b10: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
8b20: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8b30: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
8b40: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8b50: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
8b60: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8b70: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
8b80: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
8b90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8ba0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
8bb0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
8bc0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
8bd0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
8be0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
8bf0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
8c00: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
8c10: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
8c20: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
8c30: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
8c40: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8c50: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
8c60: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8c70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8c80: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8c90: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8ca0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8cb0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
8cc0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
8cd0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
8ce0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
8cf0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
8d00: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
8d10: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
8d20: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
8d30: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
8d40: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
8d50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8d60: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
8d70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8d80: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
8d90: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
8da0: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
8db0: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
8dc0: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
8dd0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
8de0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
8df0: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
8e00: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
8e10: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
8e20: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
8e30: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
8e40: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
8e50: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
8e60: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
8e70: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
8e80: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
8e90: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
8ea0: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
8eb0: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
8ec0: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
8ed0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8ee0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
8ef0: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
8f00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8f10: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
8f20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8f30: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
8f40: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
8f50: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
8f60: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8f70: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8f80: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8f90: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8fa0: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8fb0: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
8fc0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
8fd0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8fe0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
8ff0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
9000: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
9010: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
9020: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
9030: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
9040: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
9050: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
9060: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
9070: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
9080: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
9090: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
90a0: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
90b0: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
90c0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
90d0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
90e0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
90f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9100: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9110: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
9120: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9130: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
9140: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9150: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9160: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9170: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9180: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
9190: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
91a0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
91b0: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
91c0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
91d0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
91e0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
91f0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
9200: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9210: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9220: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54  OMITTED]].** ^(T
9230: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9240: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f  _SYNC_OMITTED] o
9250: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9260: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9270: 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73  .** SQLite and s
9280: 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73  ent to all VFSes
9290: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63   in place of a c
92a0: 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63  all to the xSync
92b0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20   method.** when 
92c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
92d0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41  nection has [PRA
92e0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
92f0: 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a   set to OFF.)^.*
9300: 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a  * Some specializ
9310: 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68  ed VFSes need th
9320: 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64  is signal in ord
9330: 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f  er to operate co
9340: 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20  rrectly.** when 
9350: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
9360: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9370: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73  chronous=OFF] is
9380: 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a   set, but most .
9390: 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20  ** VFSes do not 
93a0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
93b0: 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65   and should sile
93c0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
93d0: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c   opcode..** Appl
93e0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
93f0: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9400: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9410: 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f  ] with this.** o
9420: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9430: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
9440: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
9450: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9460: 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  FSes.** that do 
9470: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9480: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9490: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
94a0: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
94b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
94c0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
94d0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
94e0: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
94f0: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
9500: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
9510: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
9520: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
9530: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
9540: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
9550: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
9560: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
9570: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
9580: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
9590: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
95a0: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
95b0: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
95c0: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
95d0: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
95e0: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
95f0: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
9600: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
9610: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
9620: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
9630: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
9640: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
9650: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
9660: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
9670: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
9680: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
9690: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
96a0: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
96b0: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
96c0: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
96d0: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
96e0: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
96f0: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
9700: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
9710: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
9720: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9730: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
9740: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
9750: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
9760: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9770: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
9780: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
9790: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
97a0: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
97b0: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
97c0: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
97d0: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
97e0: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
97f0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
9800: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
9810: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
9820: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
9830: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
9840: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
9850: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
9860: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
9870: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
9880: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
9890: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
98a0: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
98b0: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
98c0: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
98d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
98e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
98f0: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
9900: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9910: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
9920: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9930: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9940: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
9950: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
9960: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
9970: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
9980: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
9990: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
99a0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
99b0: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
99c0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
99d0: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
99e0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
99f0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
9a00: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
9a10: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
9a20: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
9a30: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
9a40: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
9a50: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
9a60: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
9a70: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
9a80: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
9a90: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
9aa0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
9ab0: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
9ac0: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
9ad0: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
9ae0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
9af0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
9b00: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
9b10: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
9b20: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
9b30: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
9b40: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
9b50: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
9b60: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
9b70: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
9b80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
9b90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9ba0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
9bb0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
9bc0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
9bd0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
9be0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
9bf0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
9c00: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
9c10: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
9c20: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
9c30: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9c40: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9c50: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9c60: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9c70: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
9c80: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
9c90: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9ca0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
9cb0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
9cc0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9cd0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
9ce0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
9cf0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
9d00: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
9d10: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
9d20: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
9d30: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
9d40: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
9d50: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
9d60: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
9d70: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
9d80: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
9d90: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
9da0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
9db0: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
9dc0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
9dd0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
9de0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
9df0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
9e00: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
9e10: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
9e20: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
9e30: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
9e40: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
9e50: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
9e60: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
9e70: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9e80: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9e90: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9ea0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9eb0: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
9ec0: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
9ed0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
9ee0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9ef0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9f00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
9f10: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
9f20: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
9f30: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
9f40: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
9f50: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
9f60: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
9f70: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
9f80: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
9f90: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
9fa0: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
9fb0: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
9fc0: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
9fd0: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
9fe0: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
9ff0: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
a000: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
a010: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a020: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
a030: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a040: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
a050: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
a060: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
a070: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
a080: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
a090: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
a0a0: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
a0b0: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
a0c0: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
a0d0: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
a0e0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
a0f0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
a100: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
a110: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
a120: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
a130: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a140: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
a150: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a160: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
a170: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
a180: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
a190: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
a1a0: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
a1b0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
a1c0: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
a1d0: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
a1e0: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
a1f0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
a200: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
a210: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
a220: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
a230: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
a240: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
a250: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
a260: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
a270: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
a280: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
a290: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
a2a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
a2b0: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
a2c0: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
a2d0: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
a2e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a2f0: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
a300: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
a310: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
a320: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
a330: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
a340: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a350: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
a360: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
a370: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
a380: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
a390: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a3a0: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
a3b0: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
a3c0: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
a3d0: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
a3e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a3f0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a400: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
a410: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
a420: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
a430: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
a440: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
a450: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
a460: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
a470: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
a480: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
a490: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
a4a0: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
a4b0: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
a4c0: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
a4d0: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
a4e0: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
a4f0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a500: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
a510: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
a520: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
a530: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
a540: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
a550: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
a560: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
a570: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
a580: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
a590: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
a5a0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
a5b0: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
a5c0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
a5d0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
a5e0: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
a5f0: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
a600: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
a610: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a620: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a630: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
a640: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
a650: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
a660: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
a670: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a680: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a690: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
a6a0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a6b0: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
a6c0: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
a6d0: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
a6e0: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
a6f0: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
a700: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
a710: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
a720: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
a730: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  nt.  ^If the [SQ
a740: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a750: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a760: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
a770: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
a780: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
a790: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
a7a0: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
a7b0: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
a7c0: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
a7d0: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
a7e0: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
a7f0: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
a800: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
a810: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
a820: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
a830: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a840: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
a850: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
a860: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
a870: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
a880: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
a890: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
a8a0: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
a8b0: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
a8c0: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
a8d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a8e0: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
a8f0: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
a900: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
a910: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d  ANDLER].** file-
a920: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
a930: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a940: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
a950: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
a960: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
a970: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
a980: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
a990: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
a9a0: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
a9b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
a9c0: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
a9d0: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
a9e0: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
a9f0: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
aa00: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
aa10: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
aa20: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
aa30: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
aa40: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
aa50: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
aa60: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
aa70: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
aa80: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
aa90: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
aaa0: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
aab0: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
aac0: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
aad0: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
aae0: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
aaf0: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
ab00: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
ab10: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
ab20: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
ab30: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
ab40: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
ab50: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
ab60: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
ab70: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
ab80: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
ab90: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
aba0: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
abb0: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
abc0: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
abd0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
abe0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66  _TEMPFILENAME] f
abf0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74  ile-control.** t
ac00: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65  o have SQLite ge
ac10: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70  nerate a.** temp
ac20: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75  orary filename u
ac30: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
ac40: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20  gorithm that is 
ac50: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65  followed to gene
ac60: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  rate.** temporar
ac70: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20  y filenames for 
ac80: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20  TEMP tables and 
ac90: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75  other internal u
aca0: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67  ses.  The.** arg
acb0: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
acc0: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77  a char** which w
acd0: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69  ill be filled wi
ace0: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  th the filename.
acf0: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ** written into 
ad00: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
ad10: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
ad20: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61  lloc()].  The ca
ad30: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69  ller should.** i
ad40: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
ad50: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65  ree()] on the re
ad60: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20  sult to avoid a 
ad70: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a  memory leak..**.
ad80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ad90: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
ada0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
adb0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
adc0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
add0: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
ade0: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
adf0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
ae00: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
ae10: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
ae20: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
ae30: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
ae40: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
ae50: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
ae60: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
ae70: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
ae80: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
ae90: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
aea0: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
aeb0: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
aec0: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
aed0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
aee0: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
aef0: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
af00: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61  ged if.** the va
af10: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70  lue originally p
af20: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67  ointed to is neg
af30: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68  ative, and so th
af40: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20  e current limit 
af50: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69  .** can be queri
af60: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e  ed by passing in
af70: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
af80: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e  negative number.
af90: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63    This.** file-c
afa0: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69  ontrol is used i
afb0: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70  nternally to imp
afc0: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d  lement [PRAGMA m
afd0: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a  map_size]..**.**
afe0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
aff0: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54  NTL_TRACE]].** T
b000: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b010: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e  _TRACE] file con
b020: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64  trol provides ad
b030: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  visory informati
b040: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53  on.** to the VFS
b050: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20   about what the 
b060: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66  higher layers of
b070: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63   the SQLite stac
b080: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20  k are doing..** 
b090: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
b0a0: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d  l is used by som
b0b0: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74  e VFS activity t
b0c0: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a  racing [shims]..
b0d0: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b0e0: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  is a zero-termin
b0f0: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69  ated string.  Hi
b100: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74  gher layers in t
b110: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61  he.** SQLite sta
b120: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20  ck may generate 
b130: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69  instances of thi
b140: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
b150: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  f.** the [SQLITE
b160: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  _USE_FCNTL_TRACE
b170: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
b180: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
b190: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
b1b0: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  OVED]].** The [S
b1c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
b1d0: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74  MOVED] file cont
b1e0: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
b1f0: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
b200: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
b210: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74  n integer and it
b220: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61   writes a boolea
b230: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  n into that inte
b240: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a  ger depending.**
b250: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e   on whether or n
b260: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20  ot the file has 
b270: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f  been renamed, mo
b280: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ved, or deleted 
b290: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20  since it.** was 
b2a0: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a  first opened..**
b2b0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
b2c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b2d0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
b2e0: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
b2f0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
b300: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
b310: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
b320: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
b330: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
b340: 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
b350: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
b360: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
b370: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
b380: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
b390: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
b3a0: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
b3b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
b3c0: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
b3d0: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
b3e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
b3f0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
b400: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
b410: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
b420: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
b430: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
b440: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b450: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
b460: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
b470: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
b480: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
b490: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
b4a0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
b4b0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
b4c0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b4d0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
b4e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
b4f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b500: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
b510: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
b520: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b530: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
b540: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
b550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b560: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
b570: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
b580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b590: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
b5a0: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
b5b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b5c0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
b5d0: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
b5e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b5f0: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
b600: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
b610: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b620: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
b630: 20 20 20 20 20 20 20 32 30 0a 0a 2f 2a 0a 2a 2a         20../*.**
b640: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
b650: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
b660: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
b670: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
b680: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
b690: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
b6a0: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
b6b0: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
b6c0: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
b6d0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
b6e0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
b6f0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
b700: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
b710: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
b720: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
b730: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
b740: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
b750: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
b760: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
b770: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
b780: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
b790: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
b7a0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
b7b0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
b7c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b7d0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
b7e0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
b7f0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
b800: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
b810: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
b820: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
b830: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
b840: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
b850: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
b860: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
b870: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
b880: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
b890: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
b8a0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
b8b0: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
b8c0: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
b8d0: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
b8e0: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
b8f0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
b900: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
b910: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
b920: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
b930: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
b940: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
b950: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
b960: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
b970: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
b980: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
b990: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
b9a0: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
b9b0: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
b9c0: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
b9d0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
b9e0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
b9f0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
ba00: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
ba10: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
ba20: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
ba30: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
ba40: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
ba50: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
ba60: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
ba70: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
ba80: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
ba90: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
baa0: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
bab0: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
bac0: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
bad0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
bae0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
baf0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
bb00: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
bb10: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
bb20: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
bb30: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
bb40: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
bb50: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
bb60: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
bb70: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
bb80: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
bb90: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
bba0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
bbb0: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
bbc0: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
bbd0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
bbe0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
bbf0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
bc00: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
bc10: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
bc20: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
bc30: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
bc40: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
bc50: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
bc60: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
bc70: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
bc80: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
bc90: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
bca0: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
bcb0: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
bcc0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
bcd0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
bce0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
bcf0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
bd00: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
bd10: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
bd20: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
bd30: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
bd40: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
bd50: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
bd60: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
bd70: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
bd80: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
bd90: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
bda0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
bdb0: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
bdc0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
bdd0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
bde0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
bdf0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
be00: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
be10: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
be20: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
be30: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
be40: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
be50: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
be60: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
be70: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
be80: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
be90: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
bea0: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
beb0: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
bec0: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
bed0: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
bee0: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
bef0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
bf00: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
bf10: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
bf20: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
bf30: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
bf40: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
bf50: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
bf60: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
bf70: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
bf80: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
bf90: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
bfa0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
bfb0: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
bfc0: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
bfd0: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
bfe0: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
bff0: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
c000: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
c010: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
c020: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
c030: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
c040: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
c050: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
c060: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
c070: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
c080: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c090: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
c0a0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
c0b0: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
c0c0: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
c0d0: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
c0e0: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
c0f0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
c100: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
c110: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
c120: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
c130: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
c140: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
c150: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
c160: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
c170: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
c180: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
c190: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
c1a0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
c1b0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
c1c0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
c1d0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
c1e0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
c1f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
c200: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
c210: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
c220: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
c230: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
c240: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
c250: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
c260: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
c270: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
c280: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
c290: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
c2a0: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
c2b0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
c2c0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
c2d0: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
c2e0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
c2f0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
c300: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
c310: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
c320: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
c330: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
c340: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
c350: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
c360: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
c370: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
c380: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c390: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
c3a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c3b0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
c3c0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c3d0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
c3e0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c3f0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
c400: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c410: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
c420: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
c430: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
c440: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
c450: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c460: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
c470: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c480: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
c490: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
c4a0: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
c4b0: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
c4c0: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
c4d0: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
c4e0: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
c4f0: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
c500: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
c510: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
c520: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
c530: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
c540: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
c550: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
c560: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
c570: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
c580: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
c590: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
c5a0: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
c5b0: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
c5c0: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
c5d0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
c5e0: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
c5f0: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
c600: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
c610: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
c620: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
c630: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
c640: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
c650: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
c660: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
c670: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
c680: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
c690: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
c6a0: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
c6b0: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
c6c0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
c6d0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
c6e0: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
c6f0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
c700: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
c710: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
c720: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
c730: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
c740: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
c750: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
c760: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
c770: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
c780: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
c790: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
c7a0: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
c7b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
c7c0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
c7d0: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
c7e0: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
c7f0: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
c800: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
c810: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
c820: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
c830: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
c840: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
c850: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
c860: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
c870: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
c880: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
c890: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
c8a0: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
c8b0: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
c8c0: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
c8d0: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
c8e0: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
c8f0: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
c900: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
c910: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
c920: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
c930: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
c940: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
c950: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
c960: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
c970: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
c980: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
c990: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
c9a0: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
c9b0: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
c9c0: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
c9d0: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
c9e0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
c9f0: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
ca00: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
ca10: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
ca20: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
ca30: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
ca40: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
ca50: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
ca60: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
ca70: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
ca80: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
ca90: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
caa0: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
cab0: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
cac0: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
cad0: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
cae0: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
caf0: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
cb00: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
cb10: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
cb20: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
cb30: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
cb40: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
cb50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
cb60: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
cb70: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
cb80: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
cb90: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
cba0: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
cbb0: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
cbc0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
cbd0: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
cbe0: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
cbf0: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
cc00: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
cc10: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
cc20: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
cc30: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
cc40: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
cc50: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
cc60: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
cc70: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
cc80: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
cc90: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
cca0: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
ccb0: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
ccc0: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
ccd0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
cce0: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
ccf0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
cd00: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
cd10: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
cd20: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
cd30: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
cd40: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
cd50: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
cd60: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
cd70: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
cd80: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
cd90: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
cda0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
cdb0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
cdc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
cdd0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
cde0: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
cdf0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
ce00: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
ce10: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
ce20: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
ce30: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
ce40: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
ce50: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
ce60: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
ce70: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
ce80: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
ce90: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
cea0: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
ceb0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
cec0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
ced0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
cee0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
cef0: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
cf00: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
cf10: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
cf20: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
cf30: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
cf40: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
cf50: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
cf60: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
cf70: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
cf80: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
cf90: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
cfa0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
cfb0: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
cfc0: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
cfd0: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
cfe0: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
cff0: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
d000: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
d010: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
d020: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
d030: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
d040: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
d050: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
d060: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
d070: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
d080: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
d090: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
d0a0: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
d0b0: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
d0c0: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
d0d0: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
d0e0: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
d0f0: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
d100: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
d110: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
d120: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
d130: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
d140: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
d150: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
d160: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
d170: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
d180: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
d190: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
d1a0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
d1b0: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
d1c0: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
d1d0: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
d1e0: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
d1f0: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
d200: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
d210: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
d220: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
d230: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
d240: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
d250: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
d260: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
d270: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
d280: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
d290: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
d2a0: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
d2b0: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
d2c0: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
d2d0: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
d2e0: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
d2f0: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
d300: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
d310: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
d320: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
d330: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
d340: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
d350: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
d360: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
d370: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
d380: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
d390: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
d3a0: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
d3b0: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
d3c0: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
d3d0: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
d3e0: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
d3f0: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
d400: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
d410: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
d420: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
d430: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
d440: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
d450: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
d460: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
d470: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
d480: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
d490: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
d4a0: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
d4b0: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
d4c0: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
d4d0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
d4e0: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
d4f0: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
d500: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
d510: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
d520: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
d530: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
d540: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
d550: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
d560: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
d570: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
d580: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
d590: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
d5a0: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
d5b0: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
d5c0: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
d5d0: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
d5e0: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
d5f0: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
d600: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
d610: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
d620: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
d630: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
d640: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
d650: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
d660: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
d670: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
d680: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
d690: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
d6a0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
d6b0: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
d6c0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
d6d0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
d6e0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
d6f0: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
d700: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
d710: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
d720: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
d730: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
d740: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
d750: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
d760: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
d770: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
d780: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
d790: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
d7a0: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
d7b0: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
d7c0: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
d7d0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
d7e0: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
d7f0: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
d800: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
d810: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
d820: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
d830: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
d840: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
d850: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
d860: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d870: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d880: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
d890: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
d8a0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
d8b0: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
d8c0: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
d8d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
d8e0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
d8f0: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
d900: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
d910: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
d920: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
d930: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
d940: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
d950: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
d960: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
d970: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
d980: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
d990: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
d9a0: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
d9b0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
d9c0: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
d9d0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
d9e0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
d9f0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
da00: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
da10: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
da20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
da30: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
da40: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
da50: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
da60: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
da70: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
da80: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
da90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
daa0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
dab0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
dac0: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
dad0: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
dae0: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
daf0: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
db00: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
db10: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
db20: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
db30: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
db40: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
db50: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
db60: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
db70: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
db80: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
db90: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
dba0: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
dbb0: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
dbc0: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
dbd0: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
dbe0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
dbf0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
dc00: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
dc10: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
dc20: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
dc30: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
dc40: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
dc50: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
dc60: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
dc70: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
dc80: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
dc90: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
dca0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
dcb0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dcc0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
dcd0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
dce0: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
dcf0: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
dd00: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
dd10: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
dd20: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
dd30: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
dd40: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
dd50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dd60: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
dd70: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
dd80: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
dd90: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
dda0: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
ddb0: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
ddc0: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
ddd0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
dde0: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
ddf0: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
de00: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
de10: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
de20: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
de30: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
de40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
de50: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
de60: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
de70: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
de80: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
de90: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
dea0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
deb0: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
dec0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
ded0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
dee0: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
def0: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
df00: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
df10: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
df20: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
df30: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
df40: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
df50: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
df60: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
df70: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
df80: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
df90: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
dfa0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
dfb0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
dfc0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
dfd0: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
dfe0: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
dff0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
e000: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
e010: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
e020: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
e030: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
e040: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
e050: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
e060: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
e070: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
e080: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
e090: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
e0a0: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
e0b0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
e0c0: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
e0d0: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
e0e0: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
e0f0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
e100: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
e110: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
e120: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e130: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
e140: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
e150: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
e160: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e170: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
e180: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
e190: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
e1a0: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
e1b0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
e1c0: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
e1d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e1e0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
e1f0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
e200: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e210: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
e220: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
e230: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
e240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e250: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
e260: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
e270: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
e280: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
e290: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
e2a0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
e2b0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
e2c0: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
e2d0: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
e2e0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
e2f0: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
e300: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
e310: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
e320: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
e330: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
e340: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
e350: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
e360: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
e370: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
e380: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
e390: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
e3a0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
e3b0: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
e3c0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
e3d0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
e3e0: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
e3f0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
e400: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
e410: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
e420: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
e430: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
e440: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
e450: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
e460: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
e470: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
e480: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
e490: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
e4a0: 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72  iven no the corr
e4b0: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
e4c0: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
e4d0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
e4e0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
e4f0: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
e500: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
e510: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
e520: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
e530: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
e540: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
e550: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
e560: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
e570: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
e580: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
e590: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e5a0: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
e5b0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
e5c0: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
e5d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e5e0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
e5f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e600: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
e610: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
e620: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e630: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
e640: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
e650: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
e660: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
e670: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
e680: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
e690: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
e6a0: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
e6b0: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
e6c0: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
e6d0: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
e6e0: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
e6f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e700: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
e710: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
e720: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
e730: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
e740: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
e750: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e760: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
e770: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
e780: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
e790: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
e7a0: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
e7b0: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
e7c0: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
e7d0: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
e7e0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
e7f0: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
e800: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
e810: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
e820: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
e830: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
e840: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
e850: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
e860: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
e870: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
e880: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
e890: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
e8a0: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
e8b0: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
e8c0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
e8d0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
e8e0: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
e8f0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
e900: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
e910: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
e920: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
e930: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
e940: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
e950: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
e960: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
e970: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
e980: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e990: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
e9a0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
e9b0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
e9c0: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
e9d0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
e9e0: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
e9f0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
ea00: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
ea10: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
ea20: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
ea30: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
ea40: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
ea50: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ea60: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
ea70: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
ea80: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
ea90: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
eaa0: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
eab0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
eac0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
ead0: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
eae0: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
eaf0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
eb00: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
eb10: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
eb20: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
eb30: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
eb40: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
eb50: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
eb60: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
eb70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
eb80: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
eb90: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
eba0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ebb0: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
ebc0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
ebd0: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
ebe0: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
ebf0: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
ec00: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
ec10: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
ec20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
ec30: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
ec40: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
ec50: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
ec60: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
ec70: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
ec80: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
ec90: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
eca0: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
ecb0: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
ecc0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
ecd0: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
ece0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
ecf0: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
ed00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
ed10: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
ed20: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
ed30: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
ed40: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
ed50: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
ed60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
ed70: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
ed80: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
ed90: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eda0: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
edb0: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
edc0: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
edd0: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
ede0: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
edf0: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
ee00: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
ee10: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
ee20: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
ee30: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
ee40: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
ee50: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ee60: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
ee70: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
ee80: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
ee90: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
eea0: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
eeb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
eec0: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
eed0: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
eee0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
eef0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
ef00: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
ef10: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
ef20: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
ef30: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
ef40: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
ef50: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
ef60: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
ef70: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
ef80: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
ef90: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
efa0: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
efb0: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
efc0: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
efd0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
efe0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
eff0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
f000: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
f010: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
f020: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
f030: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
f040: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
f050: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
f060: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
f070: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
f080: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f090: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
f0a0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
f0b0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f0c0: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
f0d0: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
f0e0: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
f0f0: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
f100: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
f110: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f120: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
f130: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
f140: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
f150: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
f160: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
f170: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
f180: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
f190: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
f1a0: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
f1b0: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
f1c0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f1d0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
f1e0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
f1f0: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
f200: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
f210: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
f220: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
f230: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
f240: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
f250: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
f260: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
f270: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
f280: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
f290: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
f2a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
f2b0: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
f2c0: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
f2d0: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
f2e0: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
f2f0: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
f300: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
f310: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
f320: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
f330: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
f340: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
f350: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
f360: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
f370: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
f380: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
f390: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
f3a0: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
f3b0: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
f3c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
f3d0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
f3e0: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
f3f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
f400: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
f410: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
f420: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
f430: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f440: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
f450: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
f460: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
f470: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
f480: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
f490: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f4a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
f4b0: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
f4c0: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
f4d0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
f4e0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f4f0: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
f500: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
f510: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
f520: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
f530: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
f540: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
f550: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f560: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
f570: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
f580: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
f590: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
f5a0: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
f5b0: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
f5c0: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
f5d0: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
f5e0: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
f5f0: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
f600: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
f610: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
f620: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
f630: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
f640: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
f650: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
f660: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
f670: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
f680: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f690: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
f6a0: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
f6b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
f6c0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f6d0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
f6e0: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
f6f0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
f700: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
f710: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
f720: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
f730: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
f740: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f750: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
f760: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f770: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
f780: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
f790: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
f7a0: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
f7b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
f7c0: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
f7d0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f7e0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
f7f0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
f800: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
f810: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
f820: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
f830: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
f840: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
f850: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
f860: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
f870: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
f880: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
f890: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
f8a0: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
f8b0: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
f8c0: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
f8d0: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
f8e0: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
f8f0: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
f900: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
f910: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
f920: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
f930: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
f940: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f950: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
f960: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
f970: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
f980: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
f990: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
f9a0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
f9b0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
f9c0: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
f9d0: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
f9e0: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
f9f0: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
fa00: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
fa10: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
fa20: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
fa30: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
fa40: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
fa50: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fa60: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
fa70: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
fa80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
fa90: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
faa0: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
fab0: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
fac0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
fad0: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
fae0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
faf0: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
fb00: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
fb10: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
fb20: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
fb30: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
fb40: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
fb50: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
fb60: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
fb70: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
fb80: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
fb90: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
fba0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
fbb0: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
fbc0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
fbd0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
fbe0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
fbf0: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
fc00: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
fc10: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
fc20: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
fc30: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
fc40: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
fc50: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
fc60: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
fc70: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
fc80: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
fc90: 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
fca0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fcb0: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
fcc0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
fcd0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
fce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
fcf0: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
fd00: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
fd10: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
fd20: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
fd30: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
fd40: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
fd50: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
fd60: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
fd70: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
fd80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
fd90: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
fda0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
fdb0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
fdc0: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
fdd0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
fde0: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
fdf0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
fe00: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
fe10: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
fe20: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
fe30: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
fe40: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
fe50: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
fe60: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
fe70: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
fe80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
fe90: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
fea0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
feb0: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
fec0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
fed0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
fee0: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
fef0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
ff00: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
ff10: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
ff20: 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
ff30: 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
ff40: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
ff50: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
ff60: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ff70: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
ff80: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
ff90: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
ffa0: 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
ffb0: 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
ffc0: 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
ffd0: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
ffe0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
fff0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
10000 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
10010 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
10020 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
10030 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
10040 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
10050 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
10060 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10070 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
10080 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
10090 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
100a0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
100b0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
100c0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
100d0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
100e0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
100f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
10100 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
10110 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
10120 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
10130 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
10140 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
10150 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
10160 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
10170 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
10180 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
10190 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
101a0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
101b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
101c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
101d0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
101e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
101f0 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
10200 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
10210 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10220 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
10230 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
10240 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
10250 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
10260 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
10270 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
10280 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
10290 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
102a0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
102b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
102c0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
102d0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
102e0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
102f0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
10300 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
10310 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
10320 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
10330 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
10340 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
10350 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
10360 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
10370 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
10380 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10390 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
103a0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
103b0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
103c0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
103d0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
103e0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
103f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10400 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
10410 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
10420 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
10430 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
10440 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
10450 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
10460 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10470 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
10480 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
10490 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
104a0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
104b0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
104c0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
104d0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
104e0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
104f0 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
10500 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
10510 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
10520 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
10530 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
10540 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
10550 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
10560 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
10570 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
10580 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
10590 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
105a0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
105b0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
105c0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
105d0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
105e0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
105f0 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
10600 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
10610 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
10620 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
10630 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
10640 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
10650 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
10660 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
10670 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
10680 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
10690 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
106a0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
106b0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
106c0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
106d0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
106e0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
106f0 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
10700 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
10710 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
10720 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
10730 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
10740 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
10750 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
10760 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
10770 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10780 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
10790 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
107a0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
107b0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
107c0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
107d0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
107e0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
107f0 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
10800 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
10810 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
10820 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
10830 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
10840 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
10850 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
10860 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
10870 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
10880 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
10890 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
108a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
108b0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
108c0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
108d0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
108e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
108f0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
10900 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
10910 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
10920 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
10930 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
10940 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
10950 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
10960 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
10970 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
10980 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
10990 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
109a0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
109b0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
109c0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
109d0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
109e0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
109f0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
10a00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
10a10 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
10a20 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
10a30 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
10a40 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
10a50 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
10a60 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
10a70 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
10a80 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
10a90 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
10aa0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
10ab0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
10ac0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
10ad0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
10ae0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10af0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
10b00 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
10b10 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
10b20 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
10b30 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
10b40 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
10b50 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
10b60 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
10b70 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
10b80 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10b90 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
10ba0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10bb0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
10bc0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
10bd0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
10be0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
10bf0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
10c00 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
10c10 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
10c20 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
10c30 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
10c40 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
10c50 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
10c60 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
10c70 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
10c80 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
10c90 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
10ca0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
10cb0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
10cc0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
10cd0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
10ce0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
10cf0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
10d00 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
10d10 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
10d20 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10d30 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
10d40 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
10d50 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10d60 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
10d70 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
10d80 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
10d90 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
10da0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
10db0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
10dc0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
10dd0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
10de0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
10df0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
10e00 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
10e10 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
10e20 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
10e30 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
10e40 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
10e50 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
10e60 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
10e70 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
10e80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
10e90 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
10ea0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
10eb0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
10ec0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
10ed0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
10ee0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
10ef0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
10f00 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
10f10 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
10f20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
10f30 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
10f40 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
10f50 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
10f60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
10f70 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
10f80 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
10f90 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
10fa0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10fb0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
10fc0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
10fd0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10fe0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
10ff0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
11000 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
11010 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
11020 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
11030 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
11040 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11050 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
11060 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11070 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
11080 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
11090 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
110a0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
110b0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
110c0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
110d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
110e0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
110f0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
11100 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
11110 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
11120 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
11130 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11140 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
11150 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
11160 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
11170 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11180 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
11190 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
111a0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
111b0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
111c0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
111d0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
111e0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
111f0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
11200 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
11210 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11220 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11230 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
11240 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
11250 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11260 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11270 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11280 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11290 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
112a0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
112b0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
112c0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
112d0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
112e0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
112f0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
11300 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
11310 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
11320 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
11330 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11340 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11350 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11360 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11370 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11380 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11390 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
113a0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
113b0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
113c0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
113d0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
113e0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
113f0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
11400 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11410 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
11420 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
11430 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
11440 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
11450 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
11460 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11470 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11480 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11490 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
114a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
114b0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
114c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
114d0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
114e0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
114f0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11500 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11510 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
11520 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
11530 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11540 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
11550 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
11560 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11570 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11580 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11590 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
115a0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
115b0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
115c0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
115d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
115e0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
115f0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
11600 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
11610 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
11620 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
11630 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
11640 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
11650 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
11660 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
11670 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
11680 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
11690 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
116a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
116b0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
116c0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
116d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
116e0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
116f0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11700 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11710 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11720 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
11730 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
11740 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
11750 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
11760 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
11770 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11780 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11790 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
117a0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
117b0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
117c0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
117d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
117e0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
117f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11800 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
11810 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11820 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
11830 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11840 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11850 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11860 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11870 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11880 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
11890 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
118a0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
118b0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
118c0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
118d0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
118e0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
118f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11900 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
11910 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11920 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
11930 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
11940 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
11950 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
11960 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
11970 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11980 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
11990 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
119a0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
119b0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
119c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
119d0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
119e0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
119f0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
11a00 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
11a10 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
11a20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11a30 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
11a40 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
11a50 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
11a60 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
11a70 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
11a80 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
11a90 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11aa0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
11ab0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11ac0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11ad0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11ae0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
11af0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
11b00 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
11b10 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
11b20 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
11b30 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11b40 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
11b50 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
11b60 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
11b70 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
11b80 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
11b90 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
11ba0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11bc0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
11bd0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
11be0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
11bf0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
11c00 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11c10 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
11c20 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
11c30 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
11c40 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11c50 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
11c60 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
11c70 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
11c80 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
11c90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11ca0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
11cb0 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
11cc0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
11cd0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
11ce0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
11cf0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
11d00 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
11d10 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
11d20 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
11d30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
11d40 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
11d50 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
11d60 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11d70 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
11d80 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
11d90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
11da0 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
11db0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11dc0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
11dd0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
11de0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
11df0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
11e00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
11e10 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
11e20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
11e30 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
11e40 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
11e50 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
11e60 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
11e70 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
11e80 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
11e90 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
11ea0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
11eb0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
11ec0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
11ed0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
11ee0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
11ef0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
11f00 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
11f10 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
11f20 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
11f30 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
11f40 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
11f50 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
11f60 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
11f70 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11f80 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
11f90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11fa0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
11fb0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
11fc0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
11fd0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
11fe0 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
11ff0 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
12000 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
12010 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
12020 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
12030 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12040 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
12050 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
12060 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12070 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
12080 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
12090 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
120a0 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
120b0 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
120c0 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
120d0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
120e0 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
120f0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
12100 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
12110 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12120 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
12130 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
12140 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
12150 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
12160 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
12170 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12180 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
12190 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
121a0 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
121b0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
121c0 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
121d0 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
121e0 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
121f0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
12200 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
12210 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
12220 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
12230 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12240 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
12250 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12260 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
12270 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
12280 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
12290 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
122a0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
122b0 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
122c0 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
122d0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
122e0 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
122f0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
12300 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
12310 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
12320 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
12330 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
12340 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
12350 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
12360 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
12370 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
12380 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
12390 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
123a0 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
123b0 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
123c0 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
123d0 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
123e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
123f0 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
12400 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
12410 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
12420 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
12430 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
12440 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
12450 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
12460 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
12470 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
12480 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
12490 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
124a0 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
124b0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
124c0 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
124d0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
124e0 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
124f0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
12500 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
12510 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
12520 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
12530 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
12540 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
12550 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
12560 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
12570 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
12580 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
12590 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
125a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
125b0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
125c0 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
125d0 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
125e0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
125f0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
12600 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
12610 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
12620 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12630 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
12640 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
12650 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
12660 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
12670 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
12680 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
12690 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
126a0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
126b0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
126c0 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
126d0 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
126e0 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
126f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
12700 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
12710 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
12720 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
12730 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12740 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
12750 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
12760 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12770 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
12780 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
12790 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
127a0 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
127b0 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
127c0 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
127d0 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
127e0 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
127f0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
12800 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
12810 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
12820 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
12830 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
12840 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
12850 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
12860 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
12870 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
12880 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
12890 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
128a0 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
128b0 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
128c0 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
128d0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
128e0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
128f0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
12900 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
12910 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
12920 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
12930 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
12940 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
12950 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
12960 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
12970 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
12980 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
12990 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
129a0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
129b0 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
129c0 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
129d0 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
129e0 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
129f0 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
12a00 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
12a10 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
12a20 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
12a30 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
12a40 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
12a50 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
12a60 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
12a70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12a80 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
12a90 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
12aa0 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
12ab0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12ac0 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
12ad0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
12ae0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
12af0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
12b00 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
12b10 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
12b20 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
12b30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12b40 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
12b50 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
12b60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12b70 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
12b80 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
12b90 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
12ba0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
12bb0 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
12bc0 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
12bd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
12be0 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
12bf0 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
12c00 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
12c10 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
12c20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
12c30 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
12c40 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
12c50 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
12c60 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
12c70 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
12c80 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
12c90 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
12ca0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
12cb0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
12cc0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
12cd0 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
12ce0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
12cf0 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
12d00 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
12d10 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
12d20 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
12d30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12d40 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
12d50 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
12d60 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
12d70 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
12d80 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
12d90 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12da0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
12db0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
12dc0 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
12dd0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
12de0 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
12df0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
12e00 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
12e10 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
12e20 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
12e30 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
12e40 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
12e50 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
12e60 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
12e70 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
12e80 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
12e90 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
12ea0 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
12eb0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
12ec0 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
12ed0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
12ee0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
12ef0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
12f00 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
12f10 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12f20 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
12f30 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
12f40 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
12f50 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
12f60 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
12f70 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
12f80 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
12f90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12fa0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
12fb0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
12fc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12fd0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12fe0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12ff0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
13000 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
13010 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13020 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13030 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13040 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
13050 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
13060 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
13070 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
13080 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
13090 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
130a0 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
130b0 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
130c0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
130d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
130e0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
130f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13100 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13110 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
13120 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13130 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
13140 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
13150 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13160 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13170 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13180 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13190 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
131a0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
131b0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
131c0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
131d0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
131e0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
131f0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
13200 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
13210 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13220 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
13230 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
13240 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
13250 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
13260 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13270 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13280 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
13290 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
132a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
132b0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
132c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
132d0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
132e0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
132f0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13300 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13310 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13320 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
13330 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
13340 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
13350 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
13360 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
13370 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
13380 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
13390 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
133a0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
133b0 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
133c0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
133d0 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
133e0 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
133f0 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
13400 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
13410 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
13420 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
13430 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
13440 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13450 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13460 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13470 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13480 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13490 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
134a0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
134b0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
134c0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
134d0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
134e0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
134f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13500 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
13510 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
13520 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13530 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
13540 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
13550 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
13560 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
13570 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
13580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13590 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
135a0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
135b0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
135c0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
135d0 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
135e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
135f0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
13600 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
13610 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
13620 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13630 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
13640 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
13650 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
13660 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
13670 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
13680 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
13690 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
136a0 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
136b0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
136c0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
136d0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
136e0 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
136f0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
13700 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
13710 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
13720 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
13730 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
13740 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
13750 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
13760 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
13770 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
13780 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
13790 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
137a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
137b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
137c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
137d0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
137e0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
137f0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13800 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13810 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
13820 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
13830 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
13840 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
13850 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
13860 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
13870 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
13880 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
13890 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
138a0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
138b0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
138c0 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
138d0 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
138e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
138f0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
13900 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13910 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
13920 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13930 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
13940 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13950 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13960 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13970 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13980 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
13990 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
139a0 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
139b0 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
139c0 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
139d0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
139e0 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
139f0 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
13a00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13a10 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
13a20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
13a30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
13a40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13a50 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
13a60 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
13a70 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
13a80 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
13a90 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
13aa0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
13ab0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
13ac0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
13ad0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
13ae0 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
13af0 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
13b00 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
13b10 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
13b20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
13b30 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
13b40 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
13b50 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
13b60 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
13b70 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
13b80 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
13b90 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
13ba0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
13bb0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
13bc0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
13bd0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
13be0 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
13bf0 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
13c00 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
13c10 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
13c20 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
13c30 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
13c40 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
13c50 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
13c60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
13c70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
13c80 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
13c90 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
13ca0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
13cb0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
13cc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
13cd0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
13ce0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
13cf0 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
13d00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
13d10 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
13d20 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
13d30 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
13d40 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
13d50 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
13d60 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
13d70 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
13d80 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
13d90 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
13da0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
13db0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
13dc0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
13dd0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
13de0 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
13df0 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
13e00 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
13e10 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
13e20 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
13e30 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
13e40 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
13e50 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
13e60 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
13e70 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
13e80 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
13e90 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
13ea0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
13eb0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
13ec0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
13ed0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
13ee0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13ef0 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
13f00 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
13f10 64 64 3e 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  dd>^(This option
13f20 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13f30 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
13f40 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72   int. If non-zer
13f50 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68  o, then.** URI h
13f60 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
13f70 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
13f80 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
13f90 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20   zero, then URI 
13fa0 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67  handling.** is g
13fb0 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
13fc0 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64  .)^ ^If URI hand
13fd0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
13fe0 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
13ff0 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65  lenames.** passe
14000 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
14010 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
14020 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  open_v2()], [sql
14030 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
14040 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
14050 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
14060 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
14070 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
14080 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
14090 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
140a0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
140b0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
140c0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
140d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
140e0 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
140f0 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
14100 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
14110 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
14120 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
14130 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
14140 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
14150 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
14160 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
14170 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
14180 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
14190 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
141a0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
141b0 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
141c0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
141d0 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
141e0 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
141f0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
14200 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
14210 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
14220 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
14230 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14240 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
14250 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14260 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
14270 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  >^This option ta
14280 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
14290 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68  eger argument wh
142a0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
142b0 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65  ed as.** a boole
142c0 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
142d0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
142e0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
142f0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
14300 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  .** full table s
14310 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
14320 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54  y optimizer.  ^T
14330 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
14340 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
14350 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
14360 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
14370 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
14380 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14390 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
143a0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
143b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
143c0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
143d0 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
143e0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
143f0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
14400 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
14410 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
14420 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
14430 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
14440 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
14450 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
14460 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
14470 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
14480 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
14490 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
144a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
144b0 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
144c0 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
144d0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
144e0 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
144f0 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
14500 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
14510 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
14520 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14530 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
14540 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14550 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
14560 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14570 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
14580 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14590 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
145a0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
145b0 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
145c0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
145d0 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
145e0 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
145f0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
14600 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
14610 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
14620 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14630 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14640 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
14650 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
14660 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
14670 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
14680 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
14690 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
146a0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
146b0 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
146c0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
146d0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
146e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
146f0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
14700 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
14710 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
14720 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
14730 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
14740 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
14750 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
14760 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
14770 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
14780 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
14790 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
147a0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
147b0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
147c0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
147d0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
147e0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
147f0 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
14800 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
14810 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
14820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14830 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
14840 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14850 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
14860 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
14870 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
14880 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
14890 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
148a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
148b0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
148c0 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
148d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
148e0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
148f0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
14900 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14910 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
14920 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
14930 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
14940 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
14950 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
14960 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
14970 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
14980 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
14990 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
149a0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
149b0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
149c0 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
149d0 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
149e0 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
149f0 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
14a00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
14a10 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
14a20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
14a30 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
14a40 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
14a50 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
14a60 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
14a70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14a80 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
14a90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14aa0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
14ab0 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
14ac0 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
14ad0 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
14ae0 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
14af0 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
14b00 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
14b10 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
14b20 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
14b30 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
14b40 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
14b50 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
14b60 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
14b70 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
14b80 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
14b90 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
14ba0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
14bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14bc0 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
14bd0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
14be0 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
14bf0 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
14c00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
14c10 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
14c20 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
14c30 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
14c40 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63  d mmap size.** c
14c50 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
14c60 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e   at run-time.  N
14c70 6f 72 20 6d 61 79 20 74 68 65 20 6d 61 78 69 6d  or may the maxim
14c80 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
14c90 73 69 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20 74  size.** exceed t
14ca0 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
14cb0 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a  maximum mmap siz
14cc0 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  e set by the.** 
14cd0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50  [SQLITE_MAX_MMAP
14ce0 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SIZE] compile-t
14cf0 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a  ime option.)^.**
14d00 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75   ^If either argu
14d10 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74  ment to this opt
14d20 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ion is negative,
14d30 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d   then that argum
14d40 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65  ent is.** change
14d50 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65  d to its compile
14d60 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a  -time default..*
14d70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14d80 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
14d90 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
14da0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
14db0 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64  _HEAPSIZE.** <dd
14dc0 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  >^This option is
14dd0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14de0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
14df0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
14e00 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  s.** with the [S
14e10 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c  QLITE_WIN32_MALL
14e20 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OC] pre-processo
14e30 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
14e40 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
14e50 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
14e60 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
14e70 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
14e80 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
14e90 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
14ea0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
14eb0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
14ec0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
14ed0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14ee0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
14ef0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
14f00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14f10 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
14f20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
14f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14f40 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
14f50 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
14f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14f70 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
14f80 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
14f90 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
14fa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14fb0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
14fc0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
14fd0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
14fe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14ff0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
15000 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
15010 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
15020 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15030 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
15040 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
15050 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
15060 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
15070 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15080 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
15090 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
150a0 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
150b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
150c0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
150d0 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
150e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
150f0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
15100 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
15110 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15120 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
15130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15140 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
15150 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15160 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
15170 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
15180 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
15190 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
151a0 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
151b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
151c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
151d0 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
151e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
151f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
15200 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
15210 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
15220 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15230 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
15240 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
15250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15260 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
15270 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
15280 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15290 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
152a0 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
152b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
152c0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
152d0 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
152e0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
152f0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
15300 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15310 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
15320 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
15330 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
15340 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15350 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
15360 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
15370 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
15380 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
15390 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
153a0 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
153b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
153c0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
153d0 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
153e0 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
153f0 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
15400 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15410 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15420 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
15430 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a  t nByte */../*.*
15440 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
15450 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
15460 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
15470 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
15480 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
15490 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
154a0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
154b0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
154c0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
154d0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
154e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
154f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15500 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
15510 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
15520 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
15530 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
15540 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
15550 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
15560 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
15570 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
15580 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
15590 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
155a0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
155b0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
155c0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
155d0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
155e0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
155f0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
15600 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
15610 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15620 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
15630 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
15640 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
15650 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
15660 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
15670 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
15680 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
15690 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
156a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
156b0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
156c0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
156d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
156e0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
156f0 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
15700 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
15710 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
15720 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
15730 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
15740 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
15750 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
15760 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
15770 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
15780 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
15790 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
157a0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
157b0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
157c0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
157d0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
157e0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
157f0 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
15800 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
15810 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
15820 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
15830 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
15840 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
15850 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
15860 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
15870 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
15880 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
15890 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
158a0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
158b0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
158c0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
158d0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
158e0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
158f0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
15900 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
15910 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
15920 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
15930 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
15940 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
15950 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
15960 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
15970 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
15980 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
15990 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
159a0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
159b0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
159c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
159d0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
159e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
159f0 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
15a00 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
15a10 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
15a20 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
15a30 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
15a40 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
15a50 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
15a60 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
15a70 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
15a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15a90 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
15aa0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
15ab0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
15ac0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
15ad0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
15ae0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
15af0 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
15b00 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
15b10 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
15b20 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
15b30 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
15b40 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15b50 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
15b60 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
15b70 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
15b80 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
15b90 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
15ba0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
15bb0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
15bc0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
15bd0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
15be0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
15bf0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
15c00 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
15c10 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
15c20 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
15c30 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
15c40 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
15c50 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
15c60 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
15c70 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
15c80 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
15c90 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
15ca0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
15cb0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
15cc0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
15cd0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
15ce0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
15cf0 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
15d00 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
15d10 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
15d20 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
15d30 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
15d40 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
15d50 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
15d60 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
15d70 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
15d80 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
15d90 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
15da0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
15db0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
15dc0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
15dd0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
15de0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
15df0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
15e00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15e10 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
15e20 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
15e30 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
15e40 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
15e50 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
15e60 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
15e70 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
15e80 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15e90 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
15ea0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
15eb0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
15ec0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
15ed0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
15ee0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
15ef0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
15f00 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
15f10 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
15f20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15f30 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
15f40 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
15f50 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
15f60 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
15f70 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
15f80 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
15f90 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
15fa0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
15fb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15fc0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
15fd0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
15fe0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
15ff0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
16000 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
16010 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
16020 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
16030 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
16040 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
16050 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
16060 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
16070 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
16080 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
16090 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
160a0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
160b0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
160c0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
160d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
160e0 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
160f0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
16100 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16110 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16120 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
16130 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
16140 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16150 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16160 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
16170 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
16180 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
16190 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
161a0 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
161b0 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
161c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
161d0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
161e0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
161f0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
16200 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
16210 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
16220 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
16230 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
16240 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
16250 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
16260 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
16270 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
16280 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
16290 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
162a0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
162b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
162c0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
162d0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
162e0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
162f0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
16300 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
16310 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
16320 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
16330 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
16340 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
16350 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
16360 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
16370 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
16380 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
16390 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
163a0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
163b0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
163c0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
163d0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
163e0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
163f0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
16400 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
16410 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
16420 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
16430 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
16440 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
16450 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
16460 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
16470 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
16480 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
16490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
164a0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
164b0 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
164c0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
164d0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
164e0 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
164f0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
16500 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
16510 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
16520 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
16530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16540 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
16550 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
16560 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
16570 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
16580 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
16590 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
165a0 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
165b0 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
165c0 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
165d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
165e0 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
165f0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16600 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
16610 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
16620 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
16630 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
16640 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
16650 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
16660 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
16670 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
16680 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
16690 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
166a0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
166b0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
166c0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
166d0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
166e0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
166f0 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
16700 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
16710 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
16720 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
16730 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
16740 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
16750 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
16760 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
16770 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
16780 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
16790 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
167a0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
167b0 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
167c0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
167d0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
167e0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
167f0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
16800 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
16810 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
16820 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
16830 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
16840 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
16850 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
16860 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
16870 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
16880 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
16890 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
168a0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
168b0 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
168c0 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
168d0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
168e0 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
168f0 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
16900 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
16910 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
16920 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
16930 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
16940 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
16950 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
16960 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
16970 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
16980 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
16990 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
169a0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
169b0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
169c0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
169d0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
169e0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
169f0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
16a00 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
16a10 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
16a20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
16a30 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
16a40 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
16a50 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
16a60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
16a70 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
16a80 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
16a90 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
16aa0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
16ab0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
16ac0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
16ad0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
16ae0 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
16af0 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
16b00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
16b10 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
16b20 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16b30 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
16b40 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
16b50 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
16b60 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
16b70 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
16b80 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
16b90 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
16ba0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
16bb0 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
16bc0 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
16bd0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
16be0 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
16bf0 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
16c00 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
16c10 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
16c20 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
16c30 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
16c40 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
16c50 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
16c60 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
16c70 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
16c80 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
16c90 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
16ca0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
16cb0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
16cc0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
16cd0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
16ce0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
16cf0 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
16d00 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
16d10 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
16d20 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
16d30 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
16d40 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
16d50 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
16d60 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
16d70 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
16d80 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
16d90 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
16da0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
16db0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
16dc0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
16dd0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
16de0 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
16df0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
16e00 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
16e10 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
16e20 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
16e30 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
16e40 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
16e50 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
16e60 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
16e70 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
16e80 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
16e90 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
16ea0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
16eb0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
16ec0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
16ed0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
16ee0 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
16ef0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
16f00 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
16f10 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
16f20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
16f30 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
16f40 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
16f50 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
16f60 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
16f70 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
16f80 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
16f90 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
16fa0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
16fb0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
16fc0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
16fd0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
16fe0 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
16ff0 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
17000 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
17010 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
17020 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
17030 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
17040 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
17050 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
17060 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
17070 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
17080 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
17090 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
170a0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
170b0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
170c0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
170d0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
170e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
170f0 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
17100 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
17110 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
17120 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
17130 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
17140 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
17150 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
17160 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
17170 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
17180 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
17190 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
171a0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
171b0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
171c0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
171d0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
171e0 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
171f0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
17200 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
17210 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17220 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
17230 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
17240 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
17250 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
17260 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
17270 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
17280 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
17290 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
172a0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
172b0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
172c0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
172d0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
172e0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
172f0 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
17300 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
17310 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
17320 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
17330 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
17340 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
17350 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
17360 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
17370 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
17380 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
17390 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
173a0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
173b0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
173c0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
173d0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
173e0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
173f0 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
17400 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
17410 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
17420 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
17430 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
17440 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
17450 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
17460 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
17470 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
17480 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
17490 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
174a0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
174b0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
174c0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
174d0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
174e0 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
174f0 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
17500 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
17510 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17520 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
17530 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
17540 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
17550 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
17560 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
17570 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
17580 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
17590 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
175a0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
175b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
175c0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
175d0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
175e0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
175f0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
17600 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
17610 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
17620 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
17630 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
17640 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
17650 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
17660 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
17670 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
17680 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
17690 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
176a0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
176b0 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c  sed by [INSERT],
176c0 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  .** [UPDATE] or 
176d0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
176e0 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
176f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17700 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
17710 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72  ** ^(The count r
17720 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
17730 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
17740 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
17750 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20  changes.** from 
17760 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47  all [CREATE TRIG
17770 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63  GER | trigger] c
17780 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e  ontexts and chan
17790 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b  ges made by.** [
177a0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
177b0 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a  ons]. However,.*
177c0 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
177d0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
177e0 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
177f0 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d  lement [REPLACE]
17800 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
17810 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
17820 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
17830 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c  g, or [DROP TABL
17840 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20  E] processing.  
17850 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65  The.** count doe
17860 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f  s not include ro
17870 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74  ws of views that
17880 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41   fire an [INSTEA
17890 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a  D OF trigger],.*
178a0 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20  * though if the 
178b0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
178c0 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  er makes changes
178d0 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f   of its own, tho
178e0 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61  se changes .** a
178f0 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a  re counted.)^.**
17900 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f   ^The sqlite3_to
17910 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75  tal_changes() fu
17920 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68  nction counts th
17930 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f  e changes as soo
17940 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74  n as.** the stat
17950 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
17960 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74   them is complet
17970 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
17980 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a  tement handle.**
17990 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
179a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
179b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
179c0 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
179d0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
179e0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
179f0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
17a00 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
17a10 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
17a20 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
17a30 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
17a40 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
17a50 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
17a60 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
17a70 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
17a80 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
17a90 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
17aa0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
17ab0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
17ac0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
17ad0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
17ae0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
17af0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
17b00 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
17b10 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
17b20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17b30 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
17b40 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
17b50 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
17b60 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
17b70 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
17b80 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
17b90 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
17ba0 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
17bb0 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
17bc0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
17bd0 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
17be0 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
17bf0 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
17c00 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
17c10 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
17c20 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
17c30 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
17c40 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
17c50 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
17c60 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
17c70 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
17c80 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
17c90 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
17ca0 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
17cb0 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
17cc0 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
17cd0 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
17ce0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
17cf0 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
17d00 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
17d10 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
17d20 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
17d30 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
17d40 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
17d50 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
17d60 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
17d70 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
17d80 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
17d90 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
17da0 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
17db0 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
17dc0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
17dd0 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
17de0 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
17df0 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
17e00 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
17e10 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
17e20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
17e30 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
17e40 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
17e50 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
17e60 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
17e70 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
17e80 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
17e90 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
17ea0 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
17eb0 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
17ec0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
17ed0 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
17ee0 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
17ef0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
17f00 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
17f10 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
17f20 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
17f30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
17f40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
17f50 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
17f60 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
17f70 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
17f80 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
17f90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17fa0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
17fb0 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
17fc0 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
17fd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
17fe0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
17ff0 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
18000 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18010 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
18020 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
18030 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
18040 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
18050 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
18060 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
18070 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
18080 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18090 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
180a0 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
180b0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
180c0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
180d0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
180e0 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
180f0 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
18100 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
18110 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18120 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
18130 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
18140 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
18150 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
18160 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
18170 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
18180 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
18190 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
181a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
181b0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
181c0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
181d0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
181e0 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
181f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
18200 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18210 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
18220 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18230 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
18240 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
18250 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
18260 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ppen..*/.void sq
18270 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18280 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18290 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
182a0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
182b0 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
182c0 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
182d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
182e0 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
182f0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
18300 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
18310 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
18320 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
18330 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
18340 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
18350 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
18360 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
18370 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
18380 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
18390 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
183a0 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
183b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
183c0 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
183d0 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
183e0 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
183f0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
18400 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
18410 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
18420 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
18430 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
18440 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
18450 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
18460 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
18470 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
18480 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
18490 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
184a0 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
184b0 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
184c0 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
184d0 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
184e0 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
184f0 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
18500 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
18510 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
18520 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
18530 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
18540 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
18550 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
18560 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
18570 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
18580 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
18590 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
185a0 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
185b0 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
185c0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
185d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
185e0 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
185f0 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
18600 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
18610 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
18620 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
18630 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
18640 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
18650 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
18660 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
18670 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
18680 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
18690 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
186a0 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
186b0 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
186c0 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
186d0 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
186e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
186f0 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
18700 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
18710 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
18720 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
18730 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
18740 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
18750 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
18760 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18770 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
18780 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
18790 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
187a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
187b0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
187c0 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
187d0 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
187e0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
187f0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
18800 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
18810 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
18820 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
18830 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
18840 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
18850 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
18860 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
18870 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
18880 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18890 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
188a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
188b0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
188c0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
188d0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
188e0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
188f0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
18900 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
18910 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
18920 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
18930 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
18940 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
18950 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
18960 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
18970 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
18980 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
18990 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
189a0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
189b0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
189c0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
189d0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
189e0 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
189f0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
18a00 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
18a10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
18a20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
18a30 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
18a40 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
18a50 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
18a60 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
18a70 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
18a80 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
18a90 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
18aa0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
18ab0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
18ac0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
18ad0 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
18ae0 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
18af0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
18b00 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
18b10 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
18b20 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
18b30 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
18b40 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
18b50 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
18b60 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
18b70 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
18b80 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
18b90 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
18ba0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
18bb0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
18bc0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
18bd0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
18be0 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
18bf0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
18c00 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
18c10 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
18c20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
18c30 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
18c40 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
18c50 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
18c60 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
18c70 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
18c80 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
18c90 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
18ca0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
18cb0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
18cc0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
18cd0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
18ce0 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
18cf0 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
18d00 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
18d10 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
18d20 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
18d30 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
18d40 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
18d50 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
18d60 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
18d70 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
18d80 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
18d90 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
18da0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
18db0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
18dc0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
18dd0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
18de0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
18df0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
18e00 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
18e10 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
18e20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
18e30 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
18e40 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
18e50 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
18e60 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
18e70 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
18e80 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
18e90 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
18ea0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
18eb0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
18ec0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
18ed0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
18ee0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
18ef0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
18f00 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
18f10 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
18f20 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
18f30 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
18f40 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
18f50 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
18f60 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
18f70 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
18f80 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
18f90 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
18fa0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
18fb0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
18fc0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
18fd0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
18fe0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
18ff0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
19000 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
19010 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
19020 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
19030 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
19040 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
19050 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
19060 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
19070 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
19080 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
19090 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
190a0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
190b0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
190c0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
190d0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
190e0 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
190f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
19100 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
19110 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
19120 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
19130 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
19140 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
19150 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
19160 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
19170 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
19180 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
19190 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
191a0 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
191b0 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
191c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
191d0 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
191e0 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
191f0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
19200 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
19210 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
19220 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
19230 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
19240 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
19250 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
19260 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
19270 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
19280 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
19290 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
192a0 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
192b0 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
192c0 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
192d0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
192e0 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
192f0 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
19300 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
19310 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
19320 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
19330 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
19340 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
19350 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
19360 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
19370 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
19380 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
19390 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
193a0 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
193b0 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
193c0 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
193d0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
193e0 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
193f0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
19400 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
19410 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
19420 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
19430 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
19440 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
19450 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
19460 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
19470 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
19480 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
19490 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
194a0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
194b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
194c0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
194d0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
194e0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
194f0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
19500 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
19510 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
19520 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19530 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
19540 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
19550 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
19560 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
19570 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
19580 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
19590 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
195a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
195b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
195c0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
195d0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
195e0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
195f0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
19600 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
19610 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
19620 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
19630 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
19640 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
19650 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
19660 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
19670 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
19680 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
19690 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
196a0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
196b0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
196c0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
196d0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
196e0 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20  y Timeout.**.** 
196f0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
19700 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
19710 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
19720 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
19730 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
19740 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
19750 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
19760 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
19770 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
19780 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
19790 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
197a0 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
197b0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
197c0 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
197d0 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
197e0 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
197f0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
19800 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
19810 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
19820 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
19830 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
19840 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
19850 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
19860 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
19870 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
19880 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
19890 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
198a0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
198b0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
198c0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
198d0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
198e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
198f0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
19900 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
19910 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
19920 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
19930 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
19940 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
19950 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
19960 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
19970 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
19980 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
19990 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
199a0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
199b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
199c0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
199d0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
199e0 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  d.)^.*/.int sqli
199f0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19a00 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
19a10 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
19a20 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
19a30 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
19a40 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
19a50 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
19a60 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
19a70 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
19a80 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
19a90 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
19aa0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
19ab0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
19ac0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
19ad0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
19ae0 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
19af0 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
19b00 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
19b10 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
19b20 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19b30 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
19b40 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
19b50 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
19b60 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
19b70 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
19b80 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
19b90 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
19ba0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
19bb0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
19bc0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
19bd0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
19be0 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
19bf0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
19c00 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
19c10 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
19c20 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
19c30 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
19c40 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
19c50 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
19c60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
19c70 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
19c80 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
19c90 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
19ca0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
19cb0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
19cc0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
19cd0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
19ce0 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
19cf0 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
19d00 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
19d10 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
19d20 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
19d30 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
19d40 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
19d50 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
19d60 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
19d70 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
19d80 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
19d90 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
19da0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
19db0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
19dc0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
19dd0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
19de0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
19df0 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
19e00 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
19e10 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
19e20 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
19e30 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
19e40 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
19e50 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
19e60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
19e70 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
19e80 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
19e90 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
19ea0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
19eb0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
19ec0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
19ed0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
19ee0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
19ef0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
19f00 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
19f10 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
19f20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
19f30 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
19f40 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
19f50 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
19f60 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
19f70 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
19f80 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
19f90 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
19fa0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
19fb0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
19fc0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
19fd0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
19fe0 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
19ff0 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1a000 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1a010 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1a020 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1a030 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1a040 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1a050 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1a060 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1a070 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1a080 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1a090 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1a0a0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1a0b0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1a0c0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1a0d0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1a0e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1a0f0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1a100 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1a110 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1a120 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a130 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1a140 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a150 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1a160 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a170 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1a180 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a190 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1a1a0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1a1b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1a1c0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1a1d0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1a1e0 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1a1f0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a200 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1a210 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1a220 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1a230 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1a240 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1a250 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1a260 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1a270 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1a280 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1a290 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1a2a0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1a2b0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1a2c0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1a2d0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1a2e0 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1a2f0 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1a300 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1a310 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1a320 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1a330 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1a340 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1a350 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a360 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1a370 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1a380 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1a390 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1a3a0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1a3b0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1a3c0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1a3d0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1a3e0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1a3f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1a400 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1a410 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1a420 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1a430 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1a440 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1a450 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1a460 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1a470 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1a480 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1a490 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1a4a0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1a4b0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1a4c0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1a4d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1a4e0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1a4f0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1a500 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1a510 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1a520 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1a530 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1a540 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1a550 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1a560 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1a570 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1a580 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1a590 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1a5a0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1a5b0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1a5c0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1a5d0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1a5e0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1a5f0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1a600 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1a610 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1a620 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1a630 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1a640 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1a650 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1a660 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1a670 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1a680 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1a690 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1a6a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1a6b0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1a6c0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1a6d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1a6e0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1a6f0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1a700 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1a710 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1a720 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1a730 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1a740 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1a750 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1a760 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1a770 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1a780 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1a790 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1a7a0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1a7b0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1a7c0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1a7d0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1a7e0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1a7f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1a800 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1a810 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1a820 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1a830 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1a840 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1a850 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1a860 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1a870 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1a880 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1a890 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1a8a0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1a8b0 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
1a8c0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1a8d0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1a8e0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1a8f0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1a900 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1a910 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1a920 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1a930 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1a940 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1a950 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1a960 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1a970 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1a980 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1a990 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1a9a0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1a9b0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1a9c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1a9d0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1a9e0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1a9f0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1aa00 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1aa10 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1aa20 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1aa30 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1aa40 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1aa50 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1aa60 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1aa70 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1aa80 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1aa90 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1aaa0 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1aab0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1aac0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1aad0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1aae0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1aaf0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1ab00 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1ab10 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1ab20 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1ab30 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1ab40 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1ab50 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1ab60 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1ab70 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1ab80 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1ab90 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1aba0 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1abb0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1abc0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1abd0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1abe0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1abf0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1ac00 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1ac10 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1ac20 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1ac30 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1ac40 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1ac50 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1ac60 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1ac70 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1ac80 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1ac90 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1aca0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1acb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1acc0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1acd0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1ace0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1acf0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1ad00 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1ad10 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1ad20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1ad30 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1ad40 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1ad50 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1ad60 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1ad70 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1ad80 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1ad90 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1ada0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1adb0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1adc0 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1add0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1ade0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1adf0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1ae00 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1ae10 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1ae20 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1ae30 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1ae40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1ae50 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1ae60 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1ae70 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1ae80 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1ae90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1aea0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1aeb0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1aec0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1aed0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1aee0 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1aef0 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1af00 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1af10 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1af20 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1af30 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1af40 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1af50 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1af60 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
1af70 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1af80 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1af90 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1afa0 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1afb0 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1afc0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1afd0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1afe0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1aff0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1b000 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1b010 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1b020 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1b030 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1b040 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1b050 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1b060 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1b070 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1b080 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1b090 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1b0a0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1b0b0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1b0c0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1b0d0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1b0e0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1b0f0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1b100 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1b110 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b120 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1b130 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1b140 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1b150 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b160 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1b170 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1b180 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1b190 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1b1a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b1b0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1b1c0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b1d0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1b1e0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1b1f0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1b200 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1b210 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1b220 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1b230 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1b240 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b250 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1b260 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1b270 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1b280 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1b290 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1b2a0 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1b2b0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1b2c0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b2d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b2e0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1b2f0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1b300 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1b310 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1b320 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b330 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1b340 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1b350 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1b360 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1b370 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1b380 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1b390 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1b3a0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b3b0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1b3c0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1b3d0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1b3e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b3f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1b400 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1b410 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1b420 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1b430 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1b440 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1b450 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1b460 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1b470 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1b480 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1b490 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1b4a0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1b4b0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1b4c0 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1b4d0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1b4e0 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1b4f0 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1b500 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1b510 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1b520 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1b530 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1b540 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1b550 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1b560 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1b570 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1b580 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1b590 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1b5a0 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1b5b0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b5c0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1b5d0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1b5e0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1b5f0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1b600 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1b610 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1b620 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1b630 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1b640 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1b650 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1b660 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1b670 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1b680 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1b690 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1b6a0 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1b6b0 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1b6c0 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1b6d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1b6e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1b6f0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1b700 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1b710 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1b720 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1b730 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1b740 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1b750 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1b760 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1b770 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1b780 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1b790 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1b7a0 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
1b7b0 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1b7c0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
1b7d0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
1b7e0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1b7f0 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
1b800 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1b810 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1b820 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
1b830 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1b840 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1b850 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1b860 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1b870 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1b880 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1b890 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1b8a0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1b8b0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1b8c0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1b8d0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1b8e0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1b8f0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1b900 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1b910 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1b920 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1b930 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1b940 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1b950 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1b960 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1b970 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1b980 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1b990 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1b9a0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1b9b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1b9c0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1b9d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1b9e0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1b9f0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1ba00 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1ba10 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1ba20 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1ba30 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ba40 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1ba50 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1ba60 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1ba70 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1ba80 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1ba90 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1baa0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1bab0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1bac0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1bad0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1bae0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1baf0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1bb00 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1bb10 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1bb20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1bb30 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1bb40 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1bb50 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1bb60 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1bb70 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1bb80 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1bb90 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1bba0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1bbb0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1bbc0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1bbd0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1bbe0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1bbf0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1bc00 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1bc10 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1bc20 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1bc30 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1bc40 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1bc50 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1bc60 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1bc70 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1bc80 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1bc90 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1bca0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1bcb0 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1bcc0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1bcd0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1bce0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1bcf0 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1bd00 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1bd10 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1bd20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1bd30 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1bd40 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1bd50 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1bd60 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1bd70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1bd80 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1bd90 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  loc()..**.** ^(T
1bda0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1bdb0 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
1bdc0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1bdd0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1bde0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1bdf0 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
1be00 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
1be10 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
1be20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
1be30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1be40 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
1be50 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
1be60 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49  parameter.)^ ^ I
1be70 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
1be80 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1be90 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
1bea0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1beb0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1bec0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1bed0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1bee0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
1bef0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1bf00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1bf10 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1bf20 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  c()..** ^If the 
1bf30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1bf40 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1bf50 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1bf60 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1bf70 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1bf80 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1bf90 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1bfa0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
1bfb0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
1bfc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1bfd0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1bfe0 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  oc()..** ^sqlite
1bff0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
1c000 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c010 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1c020 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1c030 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1c040 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
1c050 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1c060 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
1c070 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1c080 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1c090 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1c0a0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1c0b0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1c0c0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1c0d0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1c0e0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1c0f0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1c100 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1c110 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
1c120 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1c130 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
1c140 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c150 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
1c160 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
1c170 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
1c180 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1c190 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1c1a0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1c1b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
1c1c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c1d0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
1c1e0 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
1c1f0 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
1c200 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
1c210 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
1c220 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1c230 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
1c240 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
1c250 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
1c260 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
1c270 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1c280 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
1c290 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
1c2a0 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
1c2b0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
1c2c0 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
1c2d0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
1c2e0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
1c2f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1c300 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1c310 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
1c320 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
1c330 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
1c340 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
1c350 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
1c360 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
1c370 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
1c380 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
1c390 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20  version 3.7.10, 
1c3a0 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  the Windows OS i
1c3b0 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
1c3c0 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73  alled.** the sys
1c3d0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
1c3e0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
1c3f0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
1c400 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
1c410 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
1c420 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
1c430 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
1c440 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
1c450 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
1c460 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
1c470 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
1c480 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
1c490 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c4a0 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65  errors were dete
1c4b0 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
1c4c0 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20  y were reported 
1c4d0 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
1c4e0 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
1c4f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
1c500 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
1c510 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
1c520 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
1c530 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
1c540 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
1c550 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c560 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
1c570 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
1c580 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
1c590 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
1c5a0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
1c5b0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1c5c0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
1c5d0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
1c5e0 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
1c5f0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
1c600 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
1c610 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
1c620 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
1c630 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
1c640 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
1c650 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
1c660 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
1c670 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
1c680 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1c690 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
1c6a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1c6b0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
1c6c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1c6d0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
1c6e0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1c6f0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1c700 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1c710 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
1c720 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
1c730 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
1c740 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
1c750 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
1c760 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
1c770 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
1c780 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
1c790 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
1c7a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c7b0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
1c7c0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
1c7d0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1c7e0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
1c7f0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
1c800 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1c810 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
1c820 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1c830 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
1c840 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
1c850 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
1c860 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
1c870 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
1c880 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1c890 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
1c8a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1c8b0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
1c8c0 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
1c8d0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
1c8e0 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
1c8f0 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
1c900 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
1c910 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1c920 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1c930 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
1c940 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1c950 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1c960 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
1c970 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
1c980 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
1c990 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c9a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1c9b0 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
1c9c0 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
1c9d0 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
1c9e0 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
1c9f0 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
1ca00 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
1ca10 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
1ca20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1ca30 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
1ca40 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
1ca50 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1ca60 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
1ca70 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
1ca80 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
1ca90 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
1caa0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1cab0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1cac0 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
1cad0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1cae0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1caf0 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
1cb00 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
1cb10 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
1cb20 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
1cb30 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
1cb40 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1cb50 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
1cb60 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1cb70 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1cb80 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
1cb90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1cba0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
1cbb0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
1cbc0 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
1cbd0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
1cbe0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
1cbf0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
1cc00 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
1cc10 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
1cc20 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
1cc30 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
1cc40 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
1cc50 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
1cc60 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
1cc70 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
1cc80 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
1cc90 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
1cca0 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
1ccb0 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
1ccc0 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
1ccd0 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
1cce0 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
1ccf0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
1cd00 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
1cd10 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
1cd20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
1cd30 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
1cd40 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
1cd50 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
1cd60 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
1cd70 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
1cd80 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  P..**.** ^The fi
1cd90 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
1cda0 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
1cdb0 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
1cdc0 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
1cdd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
1cde0 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
1cdf0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
1ce00 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
1ce10 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
1ce20 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
1ce30 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1ce40 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1ce50 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71  * ^On all subseq
1ce60 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
1ce70 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  , the pseudo-ran
1ce80 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1ce90 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1cea0 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1ceb0 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1cec0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1ced0 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1cee0 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
1cef0 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
1cf00 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
1cf10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cf20 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
1cf30 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
1cf40 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
1cf50 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
1cf60 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
1cf70 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
1cf80 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1cf90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1cfa0 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
1cfb0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1cfc0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
1cfd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1cfe0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
1cff0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1d000 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
1d010 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1d020 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1d030 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
1d040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d050 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1d060 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
1d070 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1d080 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
1d090 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
1d0a0 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
1d0b0 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
1d0c0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
1d0d0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
1d0e0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
1d0f0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
1d100 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d110 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
1d120 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
1d130 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
1d140 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
1d150 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d160 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
1d170 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
1d180 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
1d190 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
1d1a0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
1d1b0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
1d1c0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
1d1d0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1d1e0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
1d1f0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
1d200 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1d210 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
1d220 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
1d230 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
1d240 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
1d250 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
1d260 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d270 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
1d280 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1d290 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
1d2a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
1d2b0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1d2c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
1d2d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d2e0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1d2f0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1d300 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
1d310 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1d320 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1d330 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
1d340 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1d350 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1d360 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
1d370 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
1d380 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
1d390 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
1d3a0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1d3b0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
1d3c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1d3d0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1d3e0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1d3f0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
1d400 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1d410 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1d420 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
1d430 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
1d440 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
1d450 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
1d460 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1d470 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1d480 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1d490 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
1d4a0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
1d4b0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
1d4c0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
1d4d0 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
1d4e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1d4f0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1d500 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1d510 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
1d520 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
1d530 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1d540 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
1d550 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1d560 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
1d570 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
1d580 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
1d590 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1d5a0 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
1d5b0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1d5c0 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
1d5d0 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
1d5e0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1d5f0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1d600 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
1d610 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1d620 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
1d630 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1d640 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1d650 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1d660 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1d670 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
1d680 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
1d690 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
1d6a0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
1d6b0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
1d6c0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1d6d0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
1d6e0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1d6f0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1d700 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
1d710 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1d720 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
1d730 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
1d740 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
1d750 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
1d760 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
1d770 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
1d780 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1d790 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
1d7a0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
1d7b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1d7c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
1d7d0 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
1d7e0 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
1d7f0 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
1d800 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
1d810 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
1d820 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
1d830 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
1d840 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
1d850 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
1d860 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
1d870 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1d880 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
1d890 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
1d8a0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
1d8b0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
1d8c0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
1d8d0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
1d8e0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
1d8f0 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
1d900 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
1d910 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
1d920 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
1d930 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
1d940 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
1d950 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
1d960 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
1d970 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
1d980 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
1d990 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
1d9a0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
1d9b0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
1d9c0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
1d9d0 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
1d9e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1d9f0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
1da00 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
1da10 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
1da20 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
1da30 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
1da40 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
1da50 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
1da60 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
1da70 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
1da80 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
1da90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1daa0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
1dab0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1dac0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
1dad0 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
1dae0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1daf0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
1db00 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
1db10 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
1db20 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
1db30 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
1db40 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
1db50 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
1db60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1db70 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
1db80 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
1db90 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
1dba0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1dbb0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
1dbc0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
1dbd0 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
1dbe0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
1dbf0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
1dc00 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
1dc10 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
1dc20 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
1dc30 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
1dc40 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
1dc50 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
1dc60 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
1dc70 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
1dc80 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
1dc90 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
1dca0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
1dcb0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
1dcc0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
1dcd0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
1dce0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
1dcf0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
1dd00 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1dd10 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1dd20 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1dd30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1dd40 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1dd50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1dd60 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1dd70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dd80 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1dd90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1dda0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1ddb0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1ddc0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1ddd0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1dde0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1ddf0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1de00 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1de10 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1de20 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1de30 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1de40 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1de50 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1de60 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1de70 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1de80 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1de90 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1dea0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1deb0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1dec0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1ded0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1dee0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1def0 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1df00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1df10 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1df20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1df30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1df40 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1df50 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1df60 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1df70 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1df80 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1df90 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1dfa0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1dfb0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1dfc0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1dfd0 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1dfe0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1dff0 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1e000 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1e010 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1e020 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1e030 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1e040 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1e050 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
1e060 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1e070 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1e080 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1e090 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1e0a0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1e0b0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1e0c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1e0d0 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1e0e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1e0f0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1e100 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1e110 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1e120 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1e130 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e140 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1e150 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1e160 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1e170 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1e180 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1e190 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1e1a0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1e1b0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1e1c0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1e1d0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1e1e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1e1f0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1e200 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1e210 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1e220 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1e230 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1e240 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1e250 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1e260 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42   a [SQLITE_ROLLB
1e270 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  ACK | return cod
1e280 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b  e].** from the [
1e290 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
1e2a0 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
1e2b0 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
1e2c0 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
1e2d0 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
1e2e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
1e2f0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
1e300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1e310 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
1e320 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
1e330 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
1e340 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
1e350 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e360 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
1e370 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
1e380 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1e390 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
1e3a0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
1e3b0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1e3c0 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
1e3d0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
1e3e0 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
1e3f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
1e400 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
1e410 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1e420 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1e430 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
1e440 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1e450 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
1e460 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
1e470 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
1e480 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
1e490 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
1e4a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e4b0 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
1e4c0 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
1e4d0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
1e4e0 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
1e4f0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
1e500 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
1e510 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1e520 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
1e530 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
1e540 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
1e550 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e560 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
1e570 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
1e580 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
1e590 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
1e5a0 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
1e5b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1e5c0 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
1e5d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
1e5e0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
1e5f0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
1e600 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1e610 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
1e620 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
1e630 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
1e640 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
1e650 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1e660 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
1e670 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1e680 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
1e690 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
1e6a0 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
1e6b0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
1e6c0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
1e6d0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
1e6e0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
1e6f0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
1e700 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
1e710 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
1e720 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e730 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e740 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
1e750 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
1e760 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
1e770 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
1e780 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
1e790 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1e7a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e7b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e7c0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
1e7d0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
1e7e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e7f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e800 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e810 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
1e820 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
1e830 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1e840 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1e850 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e860 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
1e870 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
1e880 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1e890 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e8a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e8b0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
1e8c0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
1e8d0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1e8e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e8f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1e900 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
1e910 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
1e920 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1e930 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e940 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1e950 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
1e960 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
1e970 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1e980 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e990 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1e9a0 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
1e9b0 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
1e9c0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1e9d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e9e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
1e9f0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1ea00 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
1ea10 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1ea20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ea30 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ea40 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1ea50 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
1ea60 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1ea70 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ea80 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1ea90 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
1eaa0 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
1eab0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1eac0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ead0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1eae0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
1eaf0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1eb00 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1eb10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1eb20 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1eb30 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
1eb40 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1eb50 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1eb60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eb70 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1eb80 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
1eb90 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1eba0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ebb0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ebc0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1ebd0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
1ebe0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1ebf0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ec00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ec10 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
1ec20 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
1ec30 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1ec40 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1ec50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ec60 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
1ec70 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
1ec80 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1ec90 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1eca0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ecb0 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
1ecc0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
1ecd0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ece0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ecf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ed00 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
1ed10 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
1ed20 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
1ed30 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
1ed40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ed50 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
1ed60 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
1ed70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1ed80 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1ed90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1eda0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1edb0 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
1edc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
1edd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ede0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
1edf0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
1ee00 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
1ee10 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
1ee20 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ee30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
1ee40 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
1ee50 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
1ee60 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1ee70 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1ee80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
1ee90 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1eea0 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
1eeb0 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
1eec0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1eed0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
1eee0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1eef0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
1ef00 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
1ef10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ef20 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
1ef30 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1ef40 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
1ef50 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
1ef60 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ef70 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
1ef80 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
1ef90 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
1efa0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1efb0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1efc0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
1efd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
1efe0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1eff0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f000 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f010 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1f020 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
1f030 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f040 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1f050 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f060 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
1f070 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
1f080 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f090 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1f0a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f0b0 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
1f0c0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
1f0d0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1f0e0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
1f0f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f100 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
1f110 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
1f120 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1f130 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
1f140 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f150 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
1f160 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
1f170 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
1f180 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1f190 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
1f1a0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
1f1b0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1f1c0 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
1f1d0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1f1e0 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
1f1f0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
1f200 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
1f210 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
1f220 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1f230 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
1f240 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1f250 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1f260 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
1f270 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
1f280 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
1f290 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
1f2a0 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
1f2b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
1f2c0 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
1f2d0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1f2e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1f2f0 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
1f300 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
1f310 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1f320 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
1f330 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
1f340 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
1f350 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
1f360 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1f370 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
1f380 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
1f390 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
1f3a0 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
1f3b0 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
1f3c0 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
1f3d0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
1f3e0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
1f3f0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
1f400 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
1f410 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   The [SQLITE_TRA
1f420 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
1f430 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
1f440 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
1f450 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c  o limit.** the l
1f460 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20  ength of [bound 
1f470 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e  parameter] expan
1f480 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70  sion in the outp
1f490 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72  ut of sqlite3_tr
1f4a0 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ace()..**.** ^Th
1f4b0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1f4c0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1f4d0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1f4e0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1f4f0 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1f500 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1f510 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1f520 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
1f530 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
1f540 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
1f550 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
1f560 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
1f570 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
1f580 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
1f590 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
1f5a0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1f5b0 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
1f5c0 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
1f5d0 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
1f5e0 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
1f5f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1f600 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
1f610 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
1f620 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
1f630 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
1f640 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
1f650 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
1f660 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
1f670 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1f680 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
1f690 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
1f6a0 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
1f6b0 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
1f6c0 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
1f6d0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1f6e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
1f6f0 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
1f700 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
1f710 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1f720 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
1f730 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
1f740 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1f750 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
1f760 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
1f770 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
1f780 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
1f790 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
1f7a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
1f7b0 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
1f7c0 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
1f7d0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1f7e0 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
1f7f0 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
1f800 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
1f810 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
1f820 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
1f830 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1f840 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
1f850 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
1f860 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
1f870 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
1f880 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
1f890 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1f8a0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
1f8b0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
1f8c0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1f8d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1f8e0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1f8f0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
1f900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f910 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
1f920 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
1f930 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
1f940 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
1f950 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
1f960 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
1f970 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
1f980 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
1f990 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
1f9a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1f9b0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1f9c0 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
1f9d0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
1f9e0 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
1f9f0 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
1fa00 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
1fa10 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
1fa20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
1fa30 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
1fa40 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
1fa50 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
1fa60 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
1fa70 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
1fa80 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
1fa90 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
1faa0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
1fab0 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1fac0 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1fad0 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1fae0 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1faf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fb00 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1fb10 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1fb20 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1fb30 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1fb40 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1fb50 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1fb60 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1fb70 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1fb80 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1fb90 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1fba0 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1fbb0 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1fbc0 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1fbd0 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1fbe0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1fbf0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1fc00 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1fc10 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1fc20 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1fc30 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1fc40 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1fc50 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1fc60 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1fc70 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1fc80 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1fc90 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1fca0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1fcb0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1fcc0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1fcd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1fce0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1fcf0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1fd00 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1fd10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fd20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1fd30 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1fd40 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1fd50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fd60 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1fd70 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1fd80 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1fd90 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
1fda0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1fdb0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1fdc0 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
1fdd0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1fde0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
1fdf0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
1fe00 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
1fe10 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1fe20 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
1fe30 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
1fe40 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
1fe50 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
1fe60 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
1fe70 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1fe80 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1fe90 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1fea0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1feb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1fec0 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1fed0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1fee0 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1fef0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1ff00 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
1ff10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1ff20 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
1ff30 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
1ff40 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
1ff50 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1ff60 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
1ff70 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
1ff80 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
1ff90 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1ffa0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1ffb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1ffc0 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
1ffd0 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
1ffe0 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
1fff0 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
20000 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
20010 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
20020 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
20030 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
20040 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
20050 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
20060 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
20070 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
20080 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
20090 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
200a0 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
200b0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
200c0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
200d0 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
200e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
200f0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
20100 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
20110 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
20120 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
20130 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
20140 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
20150 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
20160 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
20170 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
20180 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
20190 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
201a0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
201b0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
201c0 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
201d0 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
201e0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
201f0 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
20200 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
20210 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
20220 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
20230 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
20240 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
20250 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
20260 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
20270 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
20280 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
20290 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
202a0 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
202b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
202c0 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
202d0 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
202e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
202f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20300 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
20310 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
20320 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
20330 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
20340 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
20350 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
20360 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
20370 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
20380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20390 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
203a0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
203b0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
203c0 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
203d0 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
203e0 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
203f0 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
20400 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
20410 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
20420 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
20430 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
20440 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
20450 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
20460 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
20470 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
20480 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
20490 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
204a0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
204b0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
204c0 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
204d0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
204e0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
204f0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
20500 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
20510 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
20520 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
20530 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
20540 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
20550 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
20560 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
20570 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
20580 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
20590 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
205a0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
205b0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
205c0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
205d0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
205e0 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
205f0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
20600 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
20610 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
20620 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
20630 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
20640 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
20650 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
20660 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
20670 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
20680 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
20690 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
206a0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
206b0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
206c0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
206d0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
206e0 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
206f0 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
20700 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
20710 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
20720 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
20730 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
20740 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
20750 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
20760 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
20770 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
20780 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
20790 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
207a0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
207b0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
207c0 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
207d0 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
207e0 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
207f0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
20800 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
20810 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
20820 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
20830 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
20840 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
20850 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
20860 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
20870 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20880 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
20890 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
208a0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
208b0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
208c0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
208d0 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
208e0 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
208f0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
20900 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
20910 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
20920 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
20930 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
20940 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20950 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
20960 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
20970 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
20980 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
20990 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
209a0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
209b0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
209c0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
209d0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
209e0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
209f0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
20a00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20a10 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
20a20 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
20a30 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
20a40 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
20a50 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
20a60 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
20a70 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
20a80 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
20a90 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
20aa0 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
20ab0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
20ac0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
20ad0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
20ae0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
20af0 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
20b00 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
20b10 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
20b20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
20b30 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
20b40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
20b50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20b60 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
20b70 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
20b80 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
20b90 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
20ba0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
20bb0 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
20bc0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
20bd0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
20be0 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
20bf0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
20c00 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
20c10 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
20c20 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
20c30 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
20c40 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
20c50 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
20c60 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
20c70 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
20c80 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
20c90 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
20ca0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
20cb0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
20cc0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
20cd0 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
20ce0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
20cf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20d00 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
20d10 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
20d20 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
20d30 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
20d40 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
20d50 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
20d60 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
20d70 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
20d80 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
20d90 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
20da0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
20db0 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
20dc0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
20dd0 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
20de0 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
20df0 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
20e00 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
20e10 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
20e20 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
20e30 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
20e40 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
20e50 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
20e60 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
20e70 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
20e80 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
20e90 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
20ea0 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
20eb0 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
20ec0 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
20ed0 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
20ee0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20ef0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
20f00 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
20f10 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
20f20 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
20f30 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
20f40 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
20f50 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
20f60 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
20f70 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
20f80 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
20f90 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
20fa0 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
20fb0 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
20fc0 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
20fd0 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
20fe0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
20ff0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
21000 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
21010 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
21020 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
21030 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
21040 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
21050 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
21060 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
21070 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
21080 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
21090 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
210a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
210b0 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
210c0 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
210d0 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
210e0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
210f0 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
21100 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
21110 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
21120 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
21130 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
21140 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
21150 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
21160 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
21170 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
21180 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
21190 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
211a0 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
211b0 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
211c0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
211d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
211e0 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
211f0 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
21200 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
21210 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
21220 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
21230 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
21240 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
21250 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
21260 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
21270 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
21280 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
21290 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
212a0 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
212b0 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
212c0 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
212d0 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
212e0 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
212f0 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
21300 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
21310 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
21320 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
21330 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
21340 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
21350 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
21360 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
21370 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
21380 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
21390 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
213a0 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
213b0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
213c0 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
213d0 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
213e0 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
213f0 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
21400 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
21410 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
21420 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
21430 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
21440 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
21450 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
21460 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
21470 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f  ive path. .** ^O
21480 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
21490 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
214a0 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
214b0 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
214c0 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
214d0 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a  (e.g. "C:")..**.
214e0 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
214f0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
21500 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
21510 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
21520 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
21530 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
21540 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
21550 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
21560 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
21570 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
21580 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
21590 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  n]..** SQLite in
215a0 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c  terprets the fol
215b0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65  lowing three que
215c0 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
215d0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
215e0 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
215f0 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
21600 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
21610 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
21620 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
21630 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
21640 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
21650 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
21660 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
21670 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
21680 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
21690 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
216a0 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
216b0 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
216c0 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
216d0 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
216e0 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
216f0 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
21700 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
21710 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
21720 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
21730 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
21740 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
21750 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
21760 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
21770 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
21780 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
21790 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
217a0 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
217b0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
217c0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
217d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
217e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
217f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
21800 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
21810 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
21820 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
21830 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
21840 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
21850 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
21860 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
21870 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
21880 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
21890 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
218a0 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
218b0 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
218c0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
218d0 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
218e0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
218f0 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
21900 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
21910 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
21920 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
21930 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
21940 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
21950 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
21960 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
21970 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
21980 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
21990 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
219a0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
219b0 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
219c0 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
219d0 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
219e0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
219f0 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
21a00 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
21a10 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
21a20 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
21a30 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
21a40 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
21a50 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
21a60 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
21a70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
21a80 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
21a90 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
21aa0 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
21ab0 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
21ac0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
21ad0 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
21ae0 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
21af0 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
21b00 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
21b10 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
21b20 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
21b30 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
21b40 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
21b50 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
21b60 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
21b70 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
21b80 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
21b90 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
21ba0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
21bb0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
21bc0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
21bd0 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
21be0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
21bf0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
21c00 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
21c10 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
21c20 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
21c30 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
21c40 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
21c50 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
21c60 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
21c70 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
21c80 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
21c90 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
21ca0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21cb0 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
21cc0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
21cd0 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
21ce0 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
21cf0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
21d00 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
21d10 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
21d20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
21d30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
21d40 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
21d50 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
21d60 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
21d70 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
21d80 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
21d90 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
21da0 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
21db0 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
21dc0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
21dd0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
21de0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
21df0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c  CACHE flag..** <
21e00 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
21e10 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
21e20 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
21e30 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
21e40 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
21e50 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
21e60 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
21e70 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
21e80 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
21e90 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
21ea0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
21eb0 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
21ec0 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
21ed0 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
21ee0 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
21ef0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
21f00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
21f10 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
21f20 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
21f30 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
21f40 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
21f50 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
21f60 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
21f70 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
21f80 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
21f90 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
21fa0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
21fb0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
21fc0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
21fd0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
21fe0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
21ff0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
22000 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
22010 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
22020 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
22030 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
22040 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
22050 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
22060 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
22070 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
22080 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
22090 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
220a0 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
220b0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
220c0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
220d0 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
220e0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
220f0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
22100 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
22110 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
22120 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
22130 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
22140 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
22150 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
22160 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
22170 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
22180 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
22190 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
221a0 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
221b0 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
221c0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
221d0 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
221e0 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
221f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
22200 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
22210 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
22220 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
22230 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
22240 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
22250 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
22260 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
22270 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
22280 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
22290 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
222a0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
222b0 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
222c0 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
222d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
222e0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
222f0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
22300 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
22310 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
22320 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
22330 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
22340 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
22350 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
22360 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
22370 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
22380 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
22390 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
223a0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
223b0 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e  ta.db?vfs=unix-n
223c0 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20  olock <td>.**   
223d0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
223e0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
223f0 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
22400 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
22410 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72  -nolock"..** <tr
22420 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
22430 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
22440 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
22450 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
22460 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
22470 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
22480 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
22490 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
224a0 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
224b0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
224c0 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
224d0 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
224e0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
224f0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
22500 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
22510 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
22520 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
22530 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
22540 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
22550 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
22560 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
22570 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
22580 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
22590 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
225a0 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
225b0 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
225c0 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
225d0 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
225e0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
225f0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
22600 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
22610 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
22620 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
22630 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
22640 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
22650 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
22660 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
22670 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
22680 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
22690 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
226a0 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
226b0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
226c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
226d0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
226e0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
226f0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
22700 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
22710 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
22720 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
22730 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22740 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
22750 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
22760 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
22770 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
22780 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
22790 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
227a0 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
227b0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
227c0 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
227d0 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
227e0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
227f0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
22800 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
22810 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
22820 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
22830 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
22840 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
22850 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
22860 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
22870 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
22880 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
22890 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
228a0 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
228b0 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
228c0 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
228d0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
228e0 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
228f0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
22900 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
22910 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ry].*/.int sqlit
22920 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
22930 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
22940 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
22950 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
22960 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
22970 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
22980 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
22990 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
229a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
229b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
229c0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
229d0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
229e0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
229f0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
22a00 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
22a10 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
22a20 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
22a30 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
22a40 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
22a50 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
22a60 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
22a70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
22a80 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
22a90 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
22aa0 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
22ab0 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
22ac0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
22ad0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
22ae0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
22af0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
22b00 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
22b10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
22b20 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
22b30 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
22b40 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
22b50 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
22b60 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
22b70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
22b80 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
22b90 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
22ba0 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
22bb0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
22bc0 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
22bd0 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
22be0 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
22bf0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
22c00 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
22c10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
22c20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
22c30 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
22c40 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
22c50 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
22c60 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
22c70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
22c80 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
22c90 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
22ca0 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
22cb0 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
22cc0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
22cd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
22ce0 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
22cf0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
22d00 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
22d10 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
22d20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
22d30 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
22d40 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
22d50 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
22d60 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
22d70 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
22d80 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
22d90 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
22da0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
22db0 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
22dc0 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
22dd0 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
22de0 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
22df0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
22e00 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
22e10 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
22e20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
22e30 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
22e40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
22e50 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
22e60 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
22e70 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
22e80 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
22e90 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
22ea0 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
22eb0 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
22ec0 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
22ed0 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
22ee0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
22ef0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
22f00 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
22f10 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
22f20 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
22f30 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
22f40 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
22f50 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
22f60 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
22f70 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
22f80 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
22f90 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
22fa0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
22fb0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
22fc0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
22fd0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
22fe0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
22ff0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
23000 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
23010 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
23020 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
23030 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
23040 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
23050 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
23060 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
23070 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
23080 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
23090 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
230a0 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
230b0 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
230c0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
230d0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
230e0 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
230f0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
23100 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
23110 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
23120 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
23130 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
23140 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
23150 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
23160 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
23170 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
23180 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
23190 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
231a0 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
231b0 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
231c0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
231d0 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
231e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
231f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
23200 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
23210 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
23220 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
23230 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23240 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
23250 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
23260 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
23270 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
23280 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
23290 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
232a0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
232b0 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
232c0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
232d0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
232e0 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
232f0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
23300 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
23310 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
23320 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
23330 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
23340 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
23350 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
23360 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  );.int sqlite3_u
23370 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
23380 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
23390 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
233a0 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
233b0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
233c0 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
233d0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
233e0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
233f0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
23400 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
23410 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
23420 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sages.**.** ^The
23430 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
23440 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
23450 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
23460 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
23470 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
23480 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
23490 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
234a0 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
234b0 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
234c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
234d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
234e0 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
234f0 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
23500 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
23510 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
23520 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
23530 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
23540 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
23550 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
23560 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ned.  ^The sqlit
23570 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
23580 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
23590 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
235a0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
235b0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
235c0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
235d0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
235e0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
235f0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
23600 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
23610 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23620 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
23630 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
23640 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
23650 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
23660 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
23670 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
23680 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
23690 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
236a0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
236b0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
236c0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
236d0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
236e0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
236f0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
23700 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
23710 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
23720 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
23730 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
23740 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
23750 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
23760 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
23770 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
23780 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
23790 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
237a0 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
237b0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
237c0 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
237d0 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
237e0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
237f0 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
23800 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
23810 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
23820 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
23830 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
23840 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
23850 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
23860 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
23870 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
23880 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
23890 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
238a0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
238b0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
238c0 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
238d0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
238e0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
238f0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
23900 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
23910 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
23920 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
23930 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
23940 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
23950 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
23960 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
23970 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
23980 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
23990 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
239a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
239b0 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
239c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
239d0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
239e0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
239f0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
23a00 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
23a10 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
23a20 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
23a30 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
23a40 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
23a50 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
23a60 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
23a70 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
23a80 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
23a90 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
23aa0 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
23ab0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
23ac0 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
23ad0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
23ae0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
23af0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
23b00 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
23b10 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
23b20 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
23b30 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
23b40 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
23b50 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
23b60 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
23b70 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
23b80 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
23b90 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
23ba0 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
23bb0 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
23bc0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
23bd0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
23be0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
23bf0 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
23c00 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
23c10 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
23c20 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
23c30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
23c40 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
23c50 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68  ite3*);.const ch
23c60 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
23c70 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
23c80 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
23c90 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
23ca0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
23cb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
23cc0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
23cd0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
23ce0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
23cf0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
23d00 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
23d10 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
23d20 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
23d30 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
23d40 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
23d50 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
23d60 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
23d70 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
23d80 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
23d90 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
23da0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
23db0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
23dc0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
23dd0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
23de0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
23df0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
23e00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23e10 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
23e20 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
23e30 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
23e40 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
23e50 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
23e60 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
23e70 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
23e80 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
23e90 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
23ea0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
23eb0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
23ec0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
23ed0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
23ee0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
23ef0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23f00 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
23f10 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
23f20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
23f30 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
23f40 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
23f50 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
23f60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23f70 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
23f80 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
23f90 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
23fa0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
23fb0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
23fc0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
23fd0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
23fe0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
23ff0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
24000 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
24010 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
24020 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
24030 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
24040 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
24050 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
24060 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
24070 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
24080 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
24090 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
240a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
240b0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
240c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
240d0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
240e0 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
240f0 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
24100 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
24110 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
24120 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
24130 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
24140 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
24150 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
24160 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
24170 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
24180 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
24190 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
241a0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
241b0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
241c0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
241d0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
241e0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
241f0 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
24200 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
24210 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
24220 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
24230 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
24240 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
24250 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
24260 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
24270 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
24280 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
24290 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
242a0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
242b0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
242c0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
242d0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
242e0 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
242f0 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
24300 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
24310 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
24320 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
24330 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
24340 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
24350 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
24360 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
24370 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
24380 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
24390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
243a0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
243b0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
243c0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
243d0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
243e0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
243f0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
24400 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
24410 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
24420 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
24430 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
24440 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
24450 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
24460 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
24470 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
24480 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
24490 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
244a0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
244b0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
244c0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
244d0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
244e0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
244f0 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
24500 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
24510 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
24520 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
24530 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
24540 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
24550 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
24560 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
24570 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
24580 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
24590 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
245a0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
245b0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
245c0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
245d0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
245e0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
245f0 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
24600 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
24610 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
24620 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
24630 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
24640 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
24650 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
24660 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
24670 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
24680 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
24690 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
246a0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
246b0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
246c0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
246d0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
246e0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
246f0 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
24700 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
24710 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
24720 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
24730 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
24740 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
24750 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
24760 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
24770 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
24780 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
24790 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
247a0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
247b0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
247c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
247d0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
247e0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
247f0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
24800 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
24810 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
24820 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
24830 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
24840 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
24850 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
24860 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
24870 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
24880 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
24890 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
248a0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
248b0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
248c0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
248d0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
248e0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
248f0 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
24900 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
24910 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24920 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
24930 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
24940 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
24950 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
24960 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
24970 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
24980 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
24990 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
249a0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
249b0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
249c0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
249d0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
249e0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
249f0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
24a00 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
24a10 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
24a20 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
24a30 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
24a40 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
24a50 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
24a60 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
24a70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
24a80 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
24a90 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
24aa0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24ab0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
24ac0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
24ad0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
24ae0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
24af0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
24b00 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
24b10 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
24b20 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
24b30 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
24b40 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
24b50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
24b60 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
24b70 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
24b80 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
24b90 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
24ba0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
24bb0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
24bc0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
24bd0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
24be0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
24bf0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24c00 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
24c10 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
24c20 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
24c30 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
24c40 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
24c50 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
24c60 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
24c70 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
24c80 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24c90 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
24ca0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
24cb0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
24cc0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24cd0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
24ce0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
24cf0 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
24d00 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
24d10 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
24d20 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
24d30 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
24d40 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
24d50 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
24d60 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
24d70 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
24d80 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
24d90 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
24da0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
24db0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
24dc0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
24dd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
24de0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
24df0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24e00 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
24e10 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
24e20 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
24e30 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
24e40 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
24e50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
24e60 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
24e70 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
24e80 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
24e90 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
24ea0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
24eb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
24ec0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
24ed0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
24ee0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
24ef0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
24f00 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
24f10 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
24f20 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
24f30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
24f40 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
24f50 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
24f60 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24f70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
24f80 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
24f90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24fa0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
24fb0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
24fc0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
24fd0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
24fe0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
24ff0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
25000 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25010 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
25020 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
25030 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
25040 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
25050 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25060 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
25070 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
25080 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
25090 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
250a0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
250b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
250c0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
250d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
250e0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
250f0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
25100 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
25110 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
25120 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
25130 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25140 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
25150 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
25160 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
25170 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
25180 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
25190 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
251a0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
251b0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
251c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
251d0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
251e0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
251f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25200 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
25210 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
25220 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25230 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
25240 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
25250 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25260 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
25270 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
25280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25290 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
252a0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
252b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
252c0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
252d0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
252e0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
252f0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
25300 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
25310 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
25320 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
25330 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
25340 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
25350 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
25360 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
25370 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
25380 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
25390 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
253a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
253b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
253c0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
253d0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
253e0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
253f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
25400 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
25410 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
25420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25430 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
25440 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
25450 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
25460 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
25470 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
25480 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
25490 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
254a0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
254b0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
254c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
254d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
254e0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
254f0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
25500 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
25510 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
25520 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
25530 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
25540 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
25550 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
25560 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
25570 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
25580 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
25590 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
255a0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
255b0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
255c0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
255d0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
255e0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
255f0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
25600 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
25610 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
25620 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
25630 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
25640 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
25650 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
25660 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
25670 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
25680 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
25690 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
256a0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
256b0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
256c0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
256d0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
256e0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
256f0 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
25700 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
25710 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
25720 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
25730 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
25740 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
25750 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
25760 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
25770 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
25780 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
25790 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20  inator bytes as 
257a0 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74  this saves SQLit
257b0 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  e from having to
257c0 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  .** make a copy 
257d0 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  of the input str
257e0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  ing..**.** ^If p
257f0 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
25800 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
25810 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
25820 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
25830 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
25840 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
25850 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
25860 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
25870 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
25880 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
25890 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
258a0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
258b0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
258c0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
258d0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
258e0 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
258f0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
25900 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
25910 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25920 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
25930 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
25940 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
25950 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
25960 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
25970 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
25980 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
25990 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
259a0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
259b0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
259c0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
259d0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
259e0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
259f0 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
25a00 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
25a10 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
25a20 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
25a30 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
25a40 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
25a50 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
25a60 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
25a70 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
25a80 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
25a90 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
25aa0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
25ab0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
25ac0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
25ad0 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
25ae0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
25af0 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
25b00 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
25b10 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
25b20 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
25b30 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
25b40 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
25b50 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
25b60 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
25b70 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
25b80 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
25b90 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
25ba0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
25bb0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
25bc0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
25bd0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
25be0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
25bf0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
25c00 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
25c10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
25c20 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
25c30 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
25c40 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
25c50 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
25c60 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
25c70 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
25c80 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
25c90 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
25ca0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
25cb0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
25cc0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
25cd0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
25ce0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
25cf0 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
25d00 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
25d10 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
25d20 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
25d30 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
25d40 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
25d50 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
25d60 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
25d70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
25d80 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
25d90 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
25da0 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
25db0 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
25dc0 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
25dd0 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
25de0 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
25df0 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
25e00 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
25e10 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
25e20 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
25e30 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
25e40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25e50 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
25e60 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
25e70 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
25e80 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
25e90 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
25ea0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
25eb0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
25ec0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25ed0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
25ee0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
25ef0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
25f00 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
25f10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
25f20 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
25f30 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
25f40 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
25f50 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
25f60 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
25f70 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
25f80 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
25f90 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
25fa0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
25fb0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
25fc0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
25fd0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
25fe0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
25ff0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
26000 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
26010 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
26020 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
26030 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
26040 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
26050 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
26060 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
26070 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
26080 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
26090 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
260a0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
260b0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
260c0 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
260d0 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
260e0 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
260f0 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
26100 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
26110 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
26120 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
26130 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
26140 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
26150 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
26160 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
26170 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
26180 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
26190 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
261a0 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
261b0 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
261c0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
261d0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
261e0 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
261f0 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
26200 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
26210 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
26220 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
26230 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
26240 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
26250 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
26260 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
26270 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
26280 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
26290 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
262a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
262b0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
262c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
262d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
262e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
262f0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
26300 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
26310 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
26320 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
26330 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
26340 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
26350 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
26360 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
26370 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
26380 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
26390 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
263a0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
263b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
263c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
263d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
263e0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
263f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
26400 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
26410 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
26420 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
26430 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
26440 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
26450 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
26460 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
26470 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
26480 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
26490 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
264a0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
264b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
264c0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
264d0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
264e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
264f0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
26500 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
26510 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
26520 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
26530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26540 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
26550 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
26560 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
26570 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
26580 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
26590 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
265a0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
265b0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
265c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
265d0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
265e0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
265f0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
26600 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
26610 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
26620 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26630 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
26640 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
26650 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
26660 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
26670 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
26680 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
26690 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
266a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
266b0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
266c0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
266d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
266e0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
266f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
26700 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
26710 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
26720 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
26730 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
26740 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
26750 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
26760 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
26770 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
26780 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
26790 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
267a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
267b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
267c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
267d0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
267e0 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
267f0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
26800 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
26810 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
26820 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
26830 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
26840 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
26850 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26860 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
26870 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
26880 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
26890 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
268a0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
268b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
268c0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
268d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
268e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
268f0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
26900 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
26910 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
26920 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
26930 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
26940 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
26950 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
26960 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
26970 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
26980 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
26990 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
269a0 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
269b0 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
269c0 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
269d0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
269e0 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
269f0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
26a00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26a10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
26a20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
26a30 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
26a40 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
26a50 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
26a60 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
26a70 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
26a80 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
26a90 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
26aa0 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
26ab0 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
26ac0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
26ad0 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
26ae0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
26af0 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
26b00 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
26b10 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
26b20 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
26b30 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
26b40 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
26b50 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
26b60 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
26b70 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
26b80 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
26b90 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
26ba0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
26bb0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
26bc0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26bd0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
26be0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
26bf0 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
26c00 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
26c10 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
26c20 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
26c30 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
26c40 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
26c50 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
26c60 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
26c70 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
26c80 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
26c90 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
26ca0 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
26cb0 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
26cc0 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
26cd0 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
26ce0 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
26cf0 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
26d00 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
26d10 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
26d20 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
26d30 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
26d40 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
26d50 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
26d60 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
26d70 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
26d80 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
26d90 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
26da0 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
26db0 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
26dc0 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
26dd0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
26de0 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
26df0 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
26e00 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
26e10 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
26e20 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
26e30 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
26e40 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  sk..*/.int sqlit
26e50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
26e60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
26e70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
26e80 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
26e90 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
26ea0 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
26eb0 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  en Reset.**.** ^
26ec0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
26ed0 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
26ee0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
26ef0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
26f00 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
26f10 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
26f20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
26f30 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
26f40 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
26f50 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
26f60 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  ot run to comple
26f70 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20  tion and/or has 
26f80 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73  not .** been res
26f90 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
26fa0 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
26fb0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
26fc0 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
26fd0 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
26fe0 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
26ff0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
27000 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
27010 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
27020 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
27030 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
27040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
27050 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
27060 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
27070 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
27080 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
27090 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
270a0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
270b0 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
270c0 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
270d0 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
270e0 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
270f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
27100 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
27110 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
27120 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
27130 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
27140 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
27150 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
27160 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
27170 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
27180 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
27190 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
271a0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
271b0 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
271c0 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
271d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
271e0 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
271f0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
27200 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
27210 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
27220 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
27230 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
27240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
27250 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
27260 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
27270 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
27280 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27290 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
272a0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
272b0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
272c0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
272d0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
272e0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
272f0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
27300 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
27310 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
27320 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
27330 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
27340 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
27350 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
27360 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
27370 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
27380 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
27390 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
273a0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
273b0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
273c0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
273d0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
273e0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
273f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
27400 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
27410 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
27420 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
27430 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
27440 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27450 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
27460 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
27470 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
27480 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
27490 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
274a0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
274b0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
274c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
274d0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
274e0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
274f0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
27500 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
27510 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
27520 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
27530 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
27540 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
27550 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
27560 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
27570 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
27580 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
27590 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
275a0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
275b0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
275c0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
275d0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
275e0 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
275f0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
27600 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
27610 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
27620 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
27630 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
27640 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
27650 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
27660 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
27670 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
27680 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
27690 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
276a0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
276b0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
276c0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
276d0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
276e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
276f0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
27700 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
27710 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
27720 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
27730 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
27740 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
27750 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
27760 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
27770 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
27780 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
27790 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
277a0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
277b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
277c0 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
277d0 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
277e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
277f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27800 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
27810 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
27820 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
27830 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
27840 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
27850 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
27860 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
27870 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
27880 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
27890 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
278a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
278b0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
278c0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
278d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
278e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
278f0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
27900 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
27910 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
27920 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
27930 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
27940 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27950 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
27960 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
27970 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
27980 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
27990 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
279a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
279b0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
279c0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
279d0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
279e0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
279f0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
27a00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
27a10 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
27a20 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
27a30 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
27a40 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
27a50 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
27a60 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
27a70 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
27a80 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
27a90 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
27aa0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
27ab0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
27ac0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
27ad0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
27ae0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
27af0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
27b00 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
27b10 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
27b20 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
27b30 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
27b40 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
27b50 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
27b60 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
27b70 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
27b80 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
27b90 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
27ba0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
27bb0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
27bc0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
27bd0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
27be0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
27bf0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
27c00 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
27c10 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
27c20 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
27c30 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
27c40 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
27c50 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
27c60 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
27c70 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
27c80 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
27c90 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
27ca0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
27cb0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
27cc0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
27cd0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
27ce0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
27cf0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
27d00 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
27d10 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
27d20 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
27d30 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
27d40 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
27d50 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
27d60 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
27d70 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
27d80 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
27d90 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
27da0 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
27db0 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
27dc0 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
27dd0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
27de0 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
27df0 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
27e00 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
27e10 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
27e20 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
27e30 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
27e40 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
27e50 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
27e60 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
27e70 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
27e80 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
27e90 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
27ea0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
27eb0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
27ec0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
27ed0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
27ee0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
27ef0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
27f00 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
27f10 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
27f20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
27f30 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
27f40 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
27f50 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
27f60 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
27f70 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
27f80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27f90 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
27fa0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
27fb0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
27fc0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
27fd0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
27fe0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
27ff0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
28000 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
28010 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
28020 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
28030 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
28040 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
28050 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
28060 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
28070 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
28080 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
28090 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
280a0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
280b0 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
280c0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
280d0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
280e0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
280f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
28100 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
28110 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
28120 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
28130 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
28140 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
28150 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
28160 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
28170 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
28180 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
28190 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
281a0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
281b0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
281c0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
281d0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
281e0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
281f0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
28200 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
28210 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
28220 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
28230 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
28240 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
28250 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
28260 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
28270 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
28280 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
28290 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
282a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
282b0 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
282c0 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
282d0 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
282e0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
282f0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
28300 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
28310 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
28320 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
28330 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
28340 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
28350 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
28360 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
28370 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
28380 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
28390 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
283a0 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
283b0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
283c0 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
283d0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
283e0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
283f0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
28400 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
28410 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
28420 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
28430 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
28440 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
28450 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
28460 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
28470 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
28480 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
28490 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
284a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
284b0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
284c0 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
284d0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
284e0 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
284f0 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
28500 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
28510 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
28520 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
28530 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
28540 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72  () then that par
28550 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
28560 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
28570 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
28580 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
28590 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
285a0 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
285b0 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
285c0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
285d0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
285e0 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
285f0 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
28600 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
28610 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
28620 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
28630 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
28640 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
28650 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
28660 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
28670 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
28680 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
28690 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
286a0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
286b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
286c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
286d0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
286e0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
286f0 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
28700 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
28710 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
28720 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
28730 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
28740 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
28750 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
28760 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
28770 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
28780 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
28790 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
287a0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
287b0 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
287c0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
287d0 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
287e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
287f0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
28800 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
28810 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
28820 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
28830 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
28840 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
28850 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
28860 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
28870 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
28880 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
28890 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
288a0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
288b0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
288c0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
288d0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
288e0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
288f0 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
28900 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
28910 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
28920 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
28930 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
28940 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
28950 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
28960 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
28970 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28980 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
28990 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
289a0 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
289b0 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
289c0 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
289d0 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
289e0 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
289f0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
28a00 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
28a10 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
28a20 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
28a30 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
28a40 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
28a50 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
28a60 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
28a70 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
28a80 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
28a90 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
28aa0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
28ab0 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
28ac0 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
28ad0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
28ae0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
28af0 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
28b00 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
28b10 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
28b20 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
28b30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
28b40 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
28b50 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
28b60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
28b70 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
28b80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
28b90 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
28ba0 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
28bb0 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
28bc0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
28bd0 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
28be0 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
28bf0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
28c00 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
28c10 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
28c20 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
28c30 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
28c40 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
28c50 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
28c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28c70 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
28c80 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
28c90 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
28ca0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
28cb0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
28cc0 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
28cd0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
28ce0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
28cf0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
28d00 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
28d10 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
28d20 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
28d30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28d40 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
28d50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
28d60 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
28d70 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
28d80 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
28d90 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
28da0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
28db0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
28dc0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
28dd0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
28de0 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
28df0 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
28e00 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
28e10 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
28e20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
28e30 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
28e40 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
28e50 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28e60 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
28e70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28e80 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
28e90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28ea0 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
28eb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
28ec0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
28ed0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
28ee0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
28ef0 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
28f00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28f10 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
28f20 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
28f30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28f40 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
28f50 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
28f60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28f70 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
28f80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
28f90 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
28fa0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
28fb0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
28fc0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
28fd0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
28fe0 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
28ff0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
29000 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29010 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
29020 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
29030 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
29040 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
29050 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
29060 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
29070 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
29080 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
29090 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
290a0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
290b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
290c0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
290d0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
290e0 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
290f0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
29100 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
29110 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
29120 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
29130 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
29140 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29150 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
29160 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
29170 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
29180 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
29190 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
291a0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
291b0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
291c0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
291d0 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
291e0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
291f0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
29200 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
29210 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
29220 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
29230 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
29240 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
29250 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
29260 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
29270 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
29280 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
29290 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
292a0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
292b0 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
292c0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
292d0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
292e0 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
292f0 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
29300 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
29310 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
29320 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
29330 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
29340 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
29350 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29360 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
29370 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
29380 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
29390 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
293a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
293b0 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
293c0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
293d0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
293e0 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
293f0 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eter.**.** ^The 
29400 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29410 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
29420 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29430 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
29440 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
29450 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
29460 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29470 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
29480 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
29490 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
294a0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
294b0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
294c0 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
294d0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
294e0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
294f0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
29500 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
29510 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
29520 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
29530 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
29540 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
29550 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
29560 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
29570 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
29580 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
29590 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
295a0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
295b0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
295c0 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
295d0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
295e0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
295f0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
29600 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
29610 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
29620 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
29630 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
29640 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
29650 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
29660 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
29670 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
29680 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
29690 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
296a0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
296b0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
296c0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
296d0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
296e0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
296f0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
29700 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
29710 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
29720 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
29730 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
29740 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
29750 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
29760 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29770 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
29780 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
29790 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
297a0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
297b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
297c0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
297d0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
297e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
297f0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
29800 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
29810 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29820 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
29830 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
29840 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
29850 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
29860 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
29870 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
29880 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
29890 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
298a0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
298b0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
298c0 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
298d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
298e0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
298f0 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
29900 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
29910 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
29920 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
29930 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
29940 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
29950 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
29960 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
29970 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
29980 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
29990 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
299a0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
299b0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
299c0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
299d0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
299e0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
299f0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
29a00 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29a10 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
29a20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29a30 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
29a40 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
29a50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29a60 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
29a70 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
29a80 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
29a90 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
29aa0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
29ab0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
29ac0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
29ad0 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
29ae0 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
29af0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29b00 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
29b10 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
29b20 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
29b30 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
29b40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29b50 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
29b60 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
29b70 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
29b80 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
29b90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
29ba0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
29bb0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
29bc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
29bd0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
29be0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
29bf0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
29c00 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
29c10 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
29c20 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
29c30 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
29c40 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
29c50 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
29c60 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
29c70 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
29c80 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
29c90 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
29ca0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
29cb0 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
29cc0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29cd0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
29ce0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
29cf0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
29d00 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
29d10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
29d20 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
29d30 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
29d40 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
29d50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
29d60 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
29d70 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
29d80 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
29d90 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
29da0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
29db0 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
29dc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
29dd0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
29de0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
29df0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
29e00 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
29e10 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
29e20 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
29e30 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
29e40 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
29e50 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
29e60 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
29e70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
29e80 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
29e90 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
29ea0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
29eb0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
29ec0 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
29ed0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
29ee0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
29ef0 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
29f00 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
29f10 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
29f20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
29f30 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
29f40 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
29f50 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
29f60 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
29f70 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
29f80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29f90 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
29fa0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
29fb0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
29fc0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
29fd0 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
29fe0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29ff0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2a000 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2a010 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2a020 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2a030 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
2a040 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2a050 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
2a060 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
2a070 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
2a080 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
2a090 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
2a0a0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
2a0b0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
2a0c0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
2a0d0 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
2a0e0 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
2a0f0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
2a100 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2a110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2a120 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
2a130 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
2a140 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
2a150 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
2a160 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
2a170 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
2a180 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
2a190 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
2a1a0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
2a1b0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
2a1c0 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
2a1d0 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
2a1e0 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
2a1f0 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
2a200 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
2a210 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2a220 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2a230 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
2a240 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a250 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2a260 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a270 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2a280 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2a290 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2a2a0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2a2b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2a2c0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2a2d0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2a2e0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2a2f0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2a300 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2a310 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2a320 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2a330 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2a340 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2a350 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2a360 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2a370 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2a380 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2a390 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2a3a0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2a3b0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2a3c0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2a3d0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2a3e0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2a3f0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2a400 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2a410 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2a420 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2a430 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2a440 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2a450 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2a460 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2a470 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2a480 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2a490 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2a4a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2a4b0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2a4c0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2a4d0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2a4e0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2a4f0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2a500 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2a510 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2a520 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2a530 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2a540 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2a550 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2a560 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2a570 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2a580 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2a590 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2a5a0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2a5b0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2a5c0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2a5d0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2a5e0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2a5f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2a600 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2a610 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a620 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2a630 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2a640 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2a650 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2a660 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2a670 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2a680 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2a690 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2a6a0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2a6b0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2a6c0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2a6d0 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2a6e0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2a6f0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2a700 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2a710 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2a720 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2a730 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2a740 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2a750 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2a760 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2a770 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2a780 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2a790 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2a7a0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2a7b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2a7c0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2a7d0 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2a7e0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2a7f0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2a800 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2a810 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2a820 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2a830 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2a840 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2a850 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2a860 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2a870 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2a880 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2a890 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2a8a0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2a8b0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2a8c0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2a8d0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2a8e0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2a8f0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2a900 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2a910 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2a920 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2a930 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2a940 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2a950 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2a960 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2a970 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2a980 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2a990 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2a9a0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2a9b0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2a9c0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2a9d0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2a9e0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2a9f0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2aa00 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2aa10 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2aa20 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2aa30 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2aa40 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2aa50 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2aa60 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2aa70 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2aa80 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2aa90 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2aaa0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2aab0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2aac0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2aad0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2aae0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2aaf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2ab00 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2ab10 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2ab20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ab30 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2ab40 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2ab50 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2ab60 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2ab70 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2ab80 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2ab90 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2aba0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2abb0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2abc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2abd0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2abe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2abf0 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
2ac00 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2ac10 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ac20 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2ac30 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2ac40 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2ac50 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2ac60 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2ac70 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2ac80 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
2ac90 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
2aca0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2acb0 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
2acc0 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
2acd0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ace0 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
2acf0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
2ad00 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
2ad10 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
2ad20 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
2ad30 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
2ad40 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2ad50 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
2ad60 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2ad70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
2ad80 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
2ad90 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
2ada0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2adb0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
2adc0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2add0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
2ade0 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
2adf0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2ae00 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2ae10 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
2ae20 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
2ae30 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2ae40 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
2ae50 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
2ae60 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
2ae70 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
2ae80 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
2ae90 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
2aea0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2aeb0 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
2aec0 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
2aed0 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
2aee0 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
2aef0 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
2af00 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
2af10 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
2af20 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
2af30 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
2af40 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
2af50 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
2af60 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
2af70 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2af80 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
2af90 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
2afa0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
2afb0 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
2afc0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
2afd0 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
2afe0 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
2aff0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
2b000 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
2b010 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
2b020 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
2b030 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
2b040 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
2b050 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
2b060 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
2b070 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
2b080 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
2b090 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
2b0a0 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
2b0b0 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
2b0c0 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
2b0d0 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
2b0e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2b0f0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2b100 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b110 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2b120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2b130 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2b140 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2b150 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2b160 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2b170 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
2b180 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2b190 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2b1a0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2b1b0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2b1c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b1d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2b1e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2b1f0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2b200 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2b210 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2b220 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2b230 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2b240 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2b250 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2b260 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2b270 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2b280 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2b290 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2b2a0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2b2b0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2b2c0 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2b2d0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2b2e0 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2b2f0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2b300 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2b310 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2b320 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2b330 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2b340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b350 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2b360 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2b370 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2b380 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2b390 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b3a0 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2b3b0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2b3c0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2b3d0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2b3e0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2b3f0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2b400 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2b410 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2b420 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2b430 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2b440 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2b450 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2b460 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2b470 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2b480 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2b490 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2b4a0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2b4b0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2b4c0 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2b4d0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2b4e0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2b4f0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2b500 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2b510 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2b520 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2b530 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2b540 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2b550 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2b560 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2b570 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2b580 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2b590 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2b5a0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2b5b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2b5c0 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2b5d0 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2b5e0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2b5f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2b600 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2b610 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2b620 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2b630 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2b640 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2b650 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2b660 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2b670 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2b680 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2b690 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2b6a0 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2b6b0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2b6c0 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2b6d0 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2b6e0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2b6f0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2b700 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2b710 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2b720 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2b730 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2b740 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2b750 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2b760 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2b770 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2b780 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2b790 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2b7a0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2b7b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2b7c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2b7d0 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2b7e0 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2b7f0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2b800 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2b810 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2b820 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2b830 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2b840 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2b850 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2b860 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2b870 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2b880 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2b890 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2b8a0 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2b8b0 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2b8c0 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2b8d0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2b8e0 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2b8f0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2b900 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2b910 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2b920 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2b930 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2b940 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2b950 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2b960 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2b970 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2b980 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2b990 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2b9a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2b9b0 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2b9c0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2b9d0 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2b9e0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2b9f0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2ba00 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2ba10 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2ba20 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2ba30 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2ba40 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2ba50 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2ba60 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2ba70 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2ba80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ba90 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2baa0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2bab0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2bac0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2bad0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2bae0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2baf0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2bb00 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2bb10 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2bb20 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2bb30 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2bb40 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2bb50 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2bb60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bb70 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2bb80 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2bb90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2bba0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2bbb0 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2bbc0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2bbd0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2bbe0 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2bbf0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2bc00 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2bc10 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2bc20 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2bc30 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2bc40 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2bc50 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2bc60 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2bc70 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2bc80 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2bc90 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2bca0 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2bcb0 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2bcc0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2bcd0 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2bce0 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2bcf0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2bd00 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2bd10 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2bd20 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2bd30 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2bd40 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2bd50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2bd60 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2bd70 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2bd80 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2bd90 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2bda0 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2bdb0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2bdc0 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2bdd0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2bde0 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2bdf0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2be00 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2be10 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2be20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2be30 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2be40 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2be50 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2be60 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2be70 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2be80 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2be90 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2bea0 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2beb0 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2bec0 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2bed0 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2bee0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2bef0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2bf00 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2bf10 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2bf20 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2bf30 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2bf40 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2bf50 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2bf60 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2bf70 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2bf80 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2bf90 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2bfa0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2bfb0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2bfc0 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2bfd0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2bfe0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2bff0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2c000 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2c010 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2c020 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2c030 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2c040 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2c050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2c060 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2c070 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2c080 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2c090 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2c0a0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2c0b0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2c0c0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2c0d0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2c0e0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2c0f0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2c100 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2c110 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2c120 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2c130 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2c140 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2c150 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2c160 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2c170 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c180 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2c190 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2c1a0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2c1b0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2c1c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2c1d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2c1e0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2c1f0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2c200 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2c210 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2c220 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2c230 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2c240 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2c250 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2c260 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2c270 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
2c280 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2c290 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2c2a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2c2b0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2c2c0 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2c2d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c2e0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2c2f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2c300 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2c310 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2c320 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
2c330 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2c340 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
2c350 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2c360 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
2c370 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
2c380 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
2c390 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
2c3a0 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
2c3b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2c3c0 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
2c3d0 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
2c3e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
2c3f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
2c400 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
2c410 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
2c420 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2c430 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
2c440 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
2c450 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2c460 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
2c470 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2c480 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2c490 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
2c4a0 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
2c4b0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2c4c0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2c4d0 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
2c4e0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2c4f0 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
2c500 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
2c510 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2c520 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2c530 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
2c540 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
2c550 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
2c560 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
2c570 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
2c580 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
2c590 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
2c5a0 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
2c5b0 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
2c5c0 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
2c5d0 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
2c5e0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2c5f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2c600 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2c610 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
2c620 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
2c630 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2c640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c650 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
2c660 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
2c670 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
2c680 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
2c690 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
2c6a0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
2c6b0 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
2c6c0 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
2c6d0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
2c6e0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2c6f0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2c700 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
2c710 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
2c720 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
2c730 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
2c740 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
2c750 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2c760 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
2c770 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
2c780 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
2c790 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
2c7a0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
2c7b0 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
2c7c0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
2c7d0 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
2c7e0 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
2c7f0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
2c800 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
2c810 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
2c820 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
2c830 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
2c840 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
2c850 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
2c860 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
2c870 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2c880 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
2c890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
2c8a0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
2c8b0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
2c8c0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2c8d0 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
2c8e0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2c8f0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
2c900 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
2c910 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
2c920 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
2c930 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
2c940 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
2c950 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
2c960 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
2c970 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
2c980 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
2c990 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2c9a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
2c9b0 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
2c9c0 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
2c9d0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2c9e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
2c9f0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
2ca00 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
2ca10 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
2ca20 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
2ca30 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
2ca40 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
2ca50 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
2ca60 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2ca70 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2ca80 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
2ca90 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
2caa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2cab0 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
2cac0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2cad0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2cae0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
2caf0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
2cb00 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
2cb10 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2cb20 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2cb30 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
2cb40 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
2cb50 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
2cb60 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2cb70 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2cb80 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
2cb90 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
2cba0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2cbb0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2cbc0 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
2cbd0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2cbe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2cbf0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
2cc00 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2cc10 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
2cc20 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
2cc30 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
2cc40 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
2cc50 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2cc60 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
2cc70 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2cc80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2cc90 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
2cca0 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
2ccb0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
2ccc0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2ccd0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
2cce0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
2ccf0 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
2cd00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
2cd10 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2cd20 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
2cd30 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
2cd40 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
2cd50 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2cd60 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
2cd70 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
2cd80 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2cd90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2cda0 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
2cdb0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2cdc0 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
2cdd0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
2cde0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
2cdf0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2ce00 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
2ce10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2ce20 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2ce30 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2ce40 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
2ce50 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
2ce60 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2ce70 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
2ce80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2ce90 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
2cea0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2ceb0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2cec0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ced0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2cee0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2cef0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2cf00 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2cf10 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2cf20 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2cf30 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2cf40 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
2cf50 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
2cf60 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2cf70 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
2cf80 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
2cf90 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
2cfa0 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
2cfb0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
2cfc0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
2cfd0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2cfe0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2cff0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
2d000 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
2d010 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
2d020 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
2d030 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
2d040 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
2d050 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
2d060 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
2d070 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d080 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
2d090 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
2d0a0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2d0b0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
2d0c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
2d0d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2d0e0 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
2d0f0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2d100 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
2d110 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2d120 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
2d130 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2d140 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2d150 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2d160 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2d170 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2d180 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2d190 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2d1a0 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
2d1b0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2d1c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d1d0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2d1e0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2d1f0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
2d200 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2d210 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2d220 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2d230 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2d240 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2d250 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
2d260 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2d270 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2d280 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2d290 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
2d2a0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2d2b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2d2c0 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2d2d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2d2e0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2d2f0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2d300 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
2d310 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
2d320 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2d330 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
2d340 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2d350 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d360 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
2d370 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2d380 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2d390 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2d3a0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2d3b0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2d3c0 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
2d3d0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2d3e0 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
2d3f0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2d400 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
2d410 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2d420 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d430 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2d440 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2d450 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2d460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d470 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
2d480 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2d490 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2d4a0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2d4b0 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
2d4c0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2d4d0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2d4e0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2d4f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2d500 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2d510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d520 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
2d530 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
2d540 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2d550 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2d560 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2d570 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2d580 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
2d590 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
2d5a0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
2d5b0 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
2d5c0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
2d5d0 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
2d5e0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2d5f0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2d600 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d610 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2d620 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2d630 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
2d640 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
2d650 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
2d660 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2d670 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
2d680 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
2d690 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2d6a0 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
2d6b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d6c0 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
2d6d0 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
2d6e0 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
2d6f0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
2d700 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
2d710 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
2d720 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
2d730 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2d740 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
2d750 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2d760 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2d770 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2d780 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
2d790 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2d7a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d7b0 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
2d7c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d7d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
2d7e0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2d7f0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2d800 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
2d810 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2d820 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
2d830 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
2d840 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d850 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2d860 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2d870 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2d880 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
2d890 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
2d8a0 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
2d8b0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2d8c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2d8d0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
2d8e0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2d8f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2d900 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
2d910 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2d920 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2d930 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2d940 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
2d950 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
2d960 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
2d970 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
2d980 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
2d990 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
2d9a0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
2d9b0 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
2d9c0 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
2d9d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2d9e0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
2d9f0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
2da00 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
2da10 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
2da20 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
2da30 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
2da40 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
2da50 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
2da60 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
2da70 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2da80 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2da90 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
2daa0 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
2dab0 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
2dac0 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
2dad0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
2dae0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2daf0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2db00 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
2db10 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2db20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2db30 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2db40 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
2db50 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2db60 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
2db70 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
2db80 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
2db90 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2dba0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
2dbb0 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
2dbc0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2dbd0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2dbe0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2dbf0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
2dc00 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
2dc10 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2dc20 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
2dc30 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2dc40 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
2dc50 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2dc60 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2dc70 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2dc80 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
2dc90 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2dca0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2dcb0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
2dcc0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
2dcd0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2dce0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
2dcf0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2dd00 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2dd10 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2dd20 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2dd30 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2dd40 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
2dd50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2dd60 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2dd70 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2dd80 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2dd90 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2dda0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2ddb0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
2ddc0 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
2ddd0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2dde0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2ddf0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2de00 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2de10 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
2de20 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
2de30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2de40 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
2de50 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2de60 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
2de70 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2de80 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2de90 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
2dea0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
2deb0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2dec0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
2ded0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
2dee0 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
2def0 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
2df00 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
2df10 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
2df20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
2df30 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
2df40 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
2df50 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
2df60 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
2df70 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
2df80 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
2df90 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
2dfa0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
2dfb0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
2dfc0 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
2dfd0 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
2dfe0 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
2dff0 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
2e000 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
2e010 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
2e020 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
2e030 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2e040 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
2e050 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2e060 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
2e070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e080 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
2e090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e0a0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
2e0b0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
2e0c0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2e0d0 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
2e0e0 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
2e0f0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
2e100 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
2e110 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2e120 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2e130 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
2e140 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
2e150 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
2e160 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2e170 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2e180 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
2e190 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
2e1a0 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
2e1b0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
2e1c0 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
2e1d0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2e1e0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2e1f0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
2e200 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e210 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
2e220 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2e230 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2e240 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2e250 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2e260 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2e270 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
2e280 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2e290 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
2e2a0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
2e2b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e2c0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2e2d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e2e0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2e2f0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2e300 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2e310 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
2e320 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2e330 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
2e340 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
2e350 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
2e360 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
2e370 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
2e380 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
2e390 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
2e3a0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
2e3b0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
2e3c0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
2e3d0 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
2e3e0 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
2e3f0 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
2e400 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
2e410 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
2e420 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
2e430 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
2e440 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
2e450 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
2e460 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
2e470 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
2e480 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
2e490 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
2e4a0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
2e4b0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
2e4c0 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
2e4d0 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
2e4e0 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
2e4f0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
2e500 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
2e510 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
2e520 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2e530 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
2e540 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2e550 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e560 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2e570 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2e580 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
2e590 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e5a0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2e5b0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2e5c0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
2e5d0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2e5e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e5f0 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
2e600 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
2e610 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
2e620 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
2e630 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
2e640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e650 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
2e660 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e670 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
2e680 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
2e690 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
2e6a0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
2e6b0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
2e6c0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2e6d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e6e0 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
2e6f0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
2e700 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
2e710 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
2e720 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2e730 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2e740 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2e750 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
2e760 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2e770 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
2e780 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
2e790 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2e7a0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
2e7b0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
2e7c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e7d0 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
2e7e0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2e7f0 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
2e800 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
2e810 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
2e820 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
2e830 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
2e840 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2e850 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e860 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e870 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
2e880 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
2e890 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
2e8a0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
2e8b0 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
2e8c0 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
2e8d0 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
2e8e0 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
2e8f0 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
2e900 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
2e910 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
2e920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e930 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
2e940 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
2e950 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
2e960 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2e970 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
2e980 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
2e990 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
2e9a0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
2e9b0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
2e9c0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
2e9d0 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
2e9e0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
2e9f0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
2ea00 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
2ea10 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
2ea20 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
2ea30 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
2ea40 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
2ea50 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
2ea60 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
2ea70 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
2ea80 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
2ea90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2eaa0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2eab0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2eac0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2ead0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
2eae0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2eaf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2eb00 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2eb10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2eb20 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
2eb30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
2eb40 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2eb50 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2eb60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2eb70 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2eb80 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2eb90 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2eba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2ebb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ebc0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2ebd0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2ebe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ebf0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2ec00 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2ec10 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ec20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ec30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ec40 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2ec50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ec60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ec70 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
2ec80 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
2ec90 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2eca0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ecb0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
2ecc0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
2ecd0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
2ece0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2ecf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ed00 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
2ed10 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2ed20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
2ed30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ed40 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
2ed50 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
2ed60 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
2ed70 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
2ed80 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
2ed90 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
2eda0 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
2edb0 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
2edc0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2edd0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
2ede0 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
2edf0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2ee00 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
2ee10 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
2ee20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
2ee30 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
2ee40 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
2ee50 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2ee60 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2ee70 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
2ee80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ee90 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
2eea0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
2eeb0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
2eec0 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
2eed0 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
2eee0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2eef0 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
2ef00 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
2ef10 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
2ef20 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
2ef30 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
2ef40 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
2ef50 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
2ef60 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
2ef70 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
2ef80 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2ef90 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
2efa0 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
2efb0 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
2efc0 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
2efd0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2efe0 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
2eff0 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
2f000 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
2f010 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
2f020 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
2f030 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
2f040 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
2f050 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
2f060 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
2f070 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
2f080 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
2f090 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
2f0a0 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
2f0b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
2f0c0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2f0d0 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
2f0e0 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
2f0f0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
2f100 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2f110 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
2f120 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
2f130 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
2f140 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
2f150 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
2f160 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
2f170 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2f180 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
2f190 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2f1a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2f1b0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
2f1c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2f1d0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
2f1e0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
2f1f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2f200 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
2f210 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f220 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
2f230 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2f240 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
2f250 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
2f260 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
2f270 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
2f280 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
2f290 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
2f2a0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
2f2b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2f2c0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
2f2d0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
2f2e0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
2f2f0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
2f300 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
2f310 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
2f320 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
2f330 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f340 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
2f350 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
2f360 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
2f370 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
2f380 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
2f390 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
2f3a0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2f3b0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2f3c0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2f3d0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2f3e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2f3f0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2f400 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
2f410 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
2f420 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2f430 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
2f440 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
2f450 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
2f460 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2f470 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2f480 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
2f490 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2f4a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2f4b0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2f4c0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2f4d0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
2f4e0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
2f4f0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
2f500 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2f510 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
2f520 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
2f530 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2f540 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2f550 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2f560 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2f570 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
2f580 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
2f590 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
2f5a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f5b0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
2f5c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
2f5d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2f5e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f5f0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
2f600 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
2f610 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
2f620 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
2f630 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
2f640 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2f650 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f660 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
2f670 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2f680 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f690 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
2f6a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
2f6b0 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
2f6c0 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
2f6d0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
2f6e0 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
2f6f0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
2f700 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2f710 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
2f720 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
2f730 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
2f740 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
2f750 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2f760 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
2f770 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
2f780 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
2f790 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
2f7a0 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
2f7b0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
2f7c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
2f7d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
2f7e0 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
2f7f0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
2f800 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
2f810 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
2f820 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
2f830 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
2f840 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2f850 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
2f860 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2f870 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2f880 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
2f890 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
2f8a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
2f8b0 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
2f8c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
2f8d0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
2f8e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2f8f0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
2f900 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f910 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
2f920 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
2f930 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
2f940 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
2f950 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
2f960 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2f970 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2f980 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2f990 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
2f9a0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
2f9b0 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
2f9c0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
2f9d0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
2f9e0 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
2f9f0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
2fa00 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
2fa10 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
2fa20 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
2fa30 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
2fa40 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
2fa50 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
2fa60 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
2fa70 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
2fa80 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
2fa90 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
2faa0 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
2fab0 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
2fac0 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
2fad0 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
2fae0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2faf0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2fb00 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
2fb10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2fb20 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
2fb30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2fb40 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
2fb50 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
2fb60 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
2fb70 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
2fb80 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2fb90 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
2fba0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
2fbb0 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
2fbc0 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
2fbd0 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
2fbe0 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2fbf0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2fc00 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
2fc10 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
2fc20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
2fc30 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
2fc40 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
2fc50 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
2fc60 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2fc70 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2fc80 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
2fc90 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
2fca0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
2fcb0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
2fcc0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
2fcd0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
2fce0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
2fcf0 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
2fd00 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2fd10 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
2fd20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
2fd30 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
2fd40 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
2fd50 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
2fd60 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
2fd70 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
2fd80 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
2fd90 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
2fda0 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
2fdb0 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
2fdc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fdd0 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
2fde0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2fdf0 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
2fe00 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
2fe10 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2fe20 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
2fe30 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
2fe40 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
2fe50 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
2fe60 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2fe70 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2fe80 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
2fe90 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
2fea0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
2feb0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
2fec0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
2fed0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
2fee0 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
2fef0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
2ff00 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
2ff10 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
2ff20 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
2ff30 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
2ff40 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
2ff50 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
2ff60 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
2ff70 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
2ff80 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
2ff90 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
2ffa0 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
2ffb0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
2ffc0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
2ffd0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
2ffe0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
2fff0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
30000 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
30010 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
30020 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
30030 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
30040 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
30050 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
30060 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
30070 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
30080 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
30090 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
300a0 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
300b0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
300c0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
300d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
300e0 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
300f0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
30100 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
30110 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
30120 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
30130 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
30140 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
30150 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
30160 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
30170 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
30180 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
30190 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
301a0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
301b0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
301c0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
301d0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
301e0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
301f0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
30200 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
30210 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
30220 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
30230 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
30240 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
30250 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
30260 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
30270 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
30280 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
30290 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
302a0 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
302b0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
302c0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
302d0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
302e0 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
302f0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
30300 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
30310 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
30320 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
30330 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
30340 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
30350 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
30360 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
30370 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
30380 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
30390 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
303a0 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
303b0 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
303c0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
303d0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
303e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
303f0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
30400 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
30410 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
30420 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
30430 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
30440 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
30450 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
30460 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
30470 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
30480 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
30490 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
304a0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
304b0 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
304c0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
304d0 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
304e0 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
304f0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
30500 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
30510 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
30520 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
30530 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
30540 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
30550 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
30560 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
30570 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
30580 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
30590 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
305a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
305b0 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
305c0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
305d0 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
305e0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
305f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
30600 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
30610 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
30620 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
30630 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
30640 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
30650 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
30660 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
30670 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
30680 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
30690 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
306a0 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
306b0 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
306c0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
306d0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
306e0 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
306f0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
30700 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
30710 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
30720 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
30730 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
30740 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
30750 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
30760 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
30770 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
30780 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
30790 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
307a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
307b0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
307c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
307d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
307e0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
307f0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
30800 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
30810 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
30820 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
30830 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
30840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
30850 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
30860 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
30870 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
30880 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
30890 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
308a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
308b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
308c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
308d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
308e0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
308f0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
30900 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
30910 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
30920 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
30930 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30940 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30950 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
30960 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
30970 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
30980 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
30990 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
309a0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
309b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
309c0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
309d0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
309e0 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
309f0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
30a00 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
30a10 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
30a20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
30a30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30a40 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30a50 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30a60 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
30a70 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30a80 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30a90 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
30aa0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
30ab0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
30ac0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
30ad0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
30ae0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
30af0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
30b00 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
30b10 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
30b20 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
30b30 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
30b40 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
30b50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
30b60 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
30b70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30b80 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
30b90 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
30ba0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
30bb0 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
30bc0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
30bd0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
30be0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
30bf0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
30c00 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
30c10 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
30c20 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
30c30 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
30c40 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
30c50 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
30c60 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
30c70 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
30c80 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
30c90 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
30ca0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
30cb0 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
30cc0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
30cd0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
30ce0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
30cf0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
30d00 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
30d10 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
30d20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
30d30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30d40 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
30d50 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
30d60 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
30d70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30d80 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
30d90 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
30da0 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
30db0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
30dc0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
30dd0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
30de0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
30df0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
30e00 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
30e10 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
30e20 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
30e30 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
30e40 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
30e50 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
30e60 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
30e70 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
30e80 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
30e90 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
30ea0 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
30eb0 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
30ec0 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
30ed0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
30ee0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
30ef0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
30f00 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
30f10 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
30f20 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
30f30 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30f40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
30f50 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
30f60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
30f70 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30f80 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
30f90 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
30fa0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
30fb0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
30fc0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
30fd0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
30fe0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
30ff0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
31000 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
31010 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
31020 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
31030 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
31040 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
31050 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
31060 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
31070 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
31080 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
31090 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
310a0 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
310b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
310c0 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
310d0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
310e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
310f0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
31100 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
31110 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
31120 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
31130 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
31140 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
31150 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
31160 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
31170 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
31180 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
31190 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
311a0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
311b0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
311c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
311d0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
311e0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
311f0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
31200 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
31210 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
31220 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
31230 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
31240 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31250 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
31260 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
31270 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
31280 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
31290 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
312a0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
312b0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
312c0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
312d0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
312e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
312f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
31300 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
31310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31320 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
31330 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31340 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
31350 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31360 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
31370 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
31380 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
31390 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
313a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
313b0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
313c0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
313d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
313e0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
313f0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
31400 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
31410 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
31420 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
31430 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
31440 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
31450 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
31460 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
31470 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
31480 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
31490 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
314a0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
314b0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
314c0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
314d0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
314e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
314f0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
31500 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
31510 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
31520 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
31530 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
31540 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
31550 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31560 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
31570 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
31580 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
31590 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
315a0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
315b0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
315c0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
315d0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
315e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
315f0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
31600 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
31610 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
31620 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
31630 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
31640 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
31650 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
31660 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
31670 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
31680 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
31690 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
316a0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
316b0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
316c0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
316d0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
316e0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
316f0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
31700 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
31710 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
31720 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
31730 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
31740 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
31750 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
31760 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
31770 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
31780 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
31790 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
317a0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
317b0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
317c0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
317d0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
317e0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
317f0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
31800 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
31810 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
31820 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
31830 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
31840 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
31850 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
31860 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
31870 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
31880 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
31890 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
318a0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
318b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
318c0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
318d0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
318e0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
318f0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
31900 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
31910 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
31920 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
31930 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
31940 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
31950 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
31960 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
31970 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
31980 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
31990 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
319a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
319b0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
319c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
319d0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
319e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
319f0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
31a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31a10 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
31a20 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
31a30 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
31a40 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
31a50 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
31a60 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
31a70 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
31a80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31a90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
31aa0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
31ab0 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
31ac0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
31ad0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
31ae0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
31af0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
31b00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31b10 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
31b20 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
31b30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31b40 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
31b50 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
31b60 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
31b70 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
31b80 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
31b90 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
31ba0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
31bb0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
31bc0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
31bd0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
31be0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
31bf0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
31c00 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
31c10 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
31c20 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
31c30 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
31c40 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
31c50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
31c60 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
31c70 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
31c80 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
31c90 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
31ca0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
31cb0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
31cc0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
31cd0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
31ce0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
31cf0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
31d00 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
31d10 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
31d20 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
31d30 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
31d40 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
31d50 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
31d60 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
31d70 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
31d80 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
31d90 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
31da0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
31db0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
31dc0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31dd0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
31de0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
31df0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
31e00 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
31e10 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
31e20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
31e30 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
31e40 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
31e50 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
31e60 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
31e70 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
31e80 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
31e90 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
31ea0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
31eb0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
31ec0 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
31ed0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
31ee0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
31ef0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
31f00 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
31f10 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
31f20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
31f30 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
31f40 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
31f50 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
31f60 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
31f70 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
31f80 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31f90 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
31fa0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
31fb0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
31fc0 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
31fd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31fe0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31ff0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
32000 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
32010 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
32020 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
32030 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
32040 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
32050 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
32060 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
32070 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
32080 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
32090 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
320a0 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
320b0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
320c0 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
320d0 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
320e0 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
320f0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
32100 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
32110 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
32120 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
32130 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
32140 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
32150 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
32160 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
32170 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
32180 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
32190 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
321a0 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
321b0 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
321c0 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
321d0 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
321e0 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
321f0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32200 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
32210 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
32220 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
32230 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
32240 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
32250 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
32260 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
32270 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
32280 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32290 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
322a0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
322b0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
322c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
322d0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
322e0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
322f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
32300 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
32310 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
32320 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
32330 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
32340 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
32350 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
32360 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
32370 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
32380 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
32390 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
323a0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
323b0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
323c0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
323d0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
323e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
323f0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
32400 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
32410 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
32420 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32430 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
32440 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
32450 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
32460 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
32470 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
32480 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
32490 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
324a0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
324b0 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
324c0 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
324d0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
324e0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
324f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32500 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
32510 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32520 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
32530 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
32540 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
32550 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
32560 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
32570 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
32580 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
32590 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
325a0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
325b0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
325c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
325d0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
325e0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
325f0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
32600 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
32610 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
32620 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
32630 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
32640 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
32650 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
32660 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
32670 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32680 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
32690 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
326a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
326b0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
326c0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
326d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
326e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
326f0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
32700 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32710 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
32720 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
32730 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
32740 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
32750 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
32760 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
32770 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
32780 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
32790 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
327a0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
327b0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
327c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
327d0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
327e0 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
327f0 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
32800 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
32810 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
32820 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
32830 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
32840 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
32850 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
32860 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
32870 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
32880 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
32890 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
328a0 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
328b0 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
328c0 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
328d0 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
328e0 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
328f0 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
32900 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
32910 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
32920 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
32930 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
32940 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
32950 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
32960 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
32970 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
32980 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
32990 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
329a0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
329b0 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
329c0 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
329d0 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
329e0 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
329f0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
32a00 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
32a10 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
32a20 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
32a30 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
32a40 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
32a50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
32a60 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
32a70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32a80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
32a90 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
32aa0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
32ab0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32ac0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
32ad0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
32ae0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
32af0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32b00 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
32b10 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
32b20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
32b30 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
32b40 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
32b50 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
32b60 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
32b70 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
32b80 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
32b90 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
32ba0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32bb0 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
32bc0 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
32bd0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
32be0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
32bf0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
32c00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32c10 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
32c20 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
32c30 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
32c40 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
32c50 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
32c60 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
32c70 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
32c80 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
32c90 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
32ca0 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
32cb0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
32cc0 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
32cd0 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
32ce0 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
32cf0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
32d00 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
32d10 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
32d20 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
32d30 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
32d40 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
32d50 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
32d60 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
32d70 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
32d80 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
32d90 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
32da0 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
32db0 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
32dc0 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
32dd0 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
32de0 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
32df0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
32e00 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
32e10 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
32e20 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
32e30 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
32e40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
32e50 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
32e60 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
32e70 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
32e80 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
32e90 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
32ea0 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
32eb0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
32ec0 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
32ed0 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
32ee0 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
32ef0 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
32f00 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
32f10 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
32f20 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
32f30 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
32f40 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
32f50 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
32f60 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
32f70 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
32f80 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32f90 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
32fa0 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
32fb0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
32fc0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
32fd0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
32fe0 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
32ff0 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
33000 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
33010 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
33020 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
33030 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
33040 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33050 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
33060 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
33070 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
33080 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
33090 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
330a0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
330b0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
330c0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
330d0 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
330e0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
330f0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
33100 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
33110 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
33120 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
33130 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
33140 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
33150 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
33160 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
33170 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
33180 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
33190 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
331a0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
331b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
331c0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
331d0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
331e0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
331f0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
33200 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
33210 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
33220 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
33230 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
33240 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
33250 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
33260 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
33270 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
33280 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
33290 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
332a0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
332b0 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
332c0 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
332d0 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
332e0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
332f0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
33300 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
33310 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
33320 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
33330 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
33340 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
33350 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
33360 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
33370 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
33380 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
33390 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
333a0 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
333b0 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
333c0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
333d0 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
333e0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
333f0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
33400 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
33410 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
33420 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
33430 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
33440 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
33450 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
33460 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
33470 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
33480 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
33490 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
334a0 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
334b0 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
334c0 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
334d0 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
334e0 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
334f0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
33500 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
33510 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
33520 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
33530 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
33540 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
33550 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
33560 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
33570 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33580 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
33590 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
335a0 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
335b0 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
335c0 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
335d0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
335e0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
335f0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
33600 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
33610 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
33620 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
33630 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
33640 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33650 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
33660 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33670 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
33680 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
33690 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
336a0 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
336b0 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
336c0 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
336d0 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
336e0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
336f0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
33700 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
33710 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
33720 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
33730 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
33740 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
33750 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
33760 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
33770 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
33780 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33790 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
337a0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
337b0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
337c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
337d0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
337e0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
337f0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
33800 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
33810 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
33820 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
33830 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
33840 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
33850 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
33860 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33870 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
33880 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
33890 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
338a0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
338b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
338c0 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
338d0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
338e0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
338f0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
33900 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
33910 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
33920 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
33930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33940 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
33950 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
33960 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
33970 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
33980 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33990 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
339a0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
339b0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
339c0 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
339d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
339e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
339f0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
33a00 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33a10 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
33a20 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
33a30 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
33a40 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
33a50 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
33a60 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
33a70 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
33a80 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
33a90 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
33aa0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33ab0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
33ac0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
33ad0 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
33ae0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
33af0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
33b00 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
33b10 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
33b20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
33b30 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
33b40 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
33b50 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
33b60 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
33b70 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33b80 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
33b90 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
33ba0 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
33bb0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
33bc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
33bd0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
33be0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33bf0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
33c00 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
33c10 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
33c20 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
33c30 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
33c40 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
33c50 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
33c60 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
33c70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
33c80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33c90 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
33ca0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33cb0 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
33cc0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
33cd0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
33ce0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
33cf0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
33d00 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
33d10 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
33d20 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
33d30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33d40 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
33d50 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33d60 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
33d70 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
33d80 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
33d90 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
33da0 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
33db0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
33dc0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
33dd0 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
33de0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
33df0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
33e00 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
33e10 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
33e20 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33e30 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
33e40 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
33e50 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
33e60 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
33e70 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
33e80 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
33e90 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
33ea0 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
33eb0 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
33ec0 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
33ed0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
33ee0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33ef0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
33f00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33f10 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
33f20 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
33f30 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
33f40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33f50 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
33f60 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
33f70 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
33f80 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
33f90 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
33fa0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
33fb0 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
33fc0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
33fd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33fe0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
33ff0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
34000 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
34010 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
34020 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
34030 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
34040 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
34050 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34060 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
34070 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34080 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
34090 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
340a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
340b0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
340c0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
340d0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
340e0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
340f0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
34100 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
34110 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
34120 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
34130 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
34140 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34150 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
34160 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
34170 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
34180 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
34190 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
341a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
341b0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
341c0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
341d0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
341e0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
341f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34200 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
34210 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
34220 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34230 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
34240 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
34250 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
34260 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
34270 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34280 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
34290 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
342a0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
342b0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
342c0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
342d0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
342e0 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
342f0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
34300 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
34310 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
34320 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
34330 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
34340 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
34350 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
34360 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
34370 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
34380 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
34390 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
343a0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
343b0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
343c0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
343d0 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
343e0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
343f0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
34400 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
34410 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
34420 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
34430 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
34440 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
34450 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
34460 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
34470 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
34480 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
34490 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
344a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
344b0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
344c0 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
344d0 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
344e0 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
344f0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
34500 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
34510 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
34520 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
34530 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
34540 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
34550 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
34560 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
34570 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
34580 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
34590 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
345a0 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
345b0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
345c0 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
345d0 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
345e0 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
345f0 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
34600 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
34610 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
34620 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
34630 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
34640 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
34650 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
34660 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
34670 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
34680 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
34690 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
346a0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
346b0 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
346c0 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
346d0 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
346e0 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
346f0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
34700 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
34710 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
34720 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
34730 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
34740 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
34750 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34760 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
34770 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
34780 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
34790 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
347a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
347b0 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
347c0 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
347d0 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
347e0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
347f0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
34800 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
34810 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
34820 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
34830 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
34840 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34850 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
34860 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
34870 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
34880 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
34890 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
348a0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
348b0 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
348c0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
348d0 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
348e0 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
348f0 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
34900 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
34910 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
34920 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
34930 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
34940 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
34950 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
34960 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34970 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34980 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
34990 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
349a0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
349b0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
349c0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
349d0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
349e0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
349f0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
34a00 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
34a10 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
34a20 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
34a30 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
34a40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34a50 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
34a60 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
34a70 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
34a80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34a90 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34aa0 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
34ab0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
34ac0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34ad0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
34ae0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34af0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
34b00 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
34b10 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
34b20 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
34b30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
34b40 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
34b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
34b60 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
34b70 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
34b80 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
34b90 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
34ba0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34bb0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
34bc0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
34bd0 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
34be0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34bf0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
34c00 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
34c10 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
34c20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34c30 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
34c40 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
34c50 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
34c60 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
34c70 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
34c80 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
34c90 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
34ca0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
34cb0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
34cc0 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
34cd0 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
34ce0 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
34cf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34d00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34d10 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
34d20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
34d30 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
34d40 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
34d50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
34d60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34d70 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
34d80 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
34d90 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
34da0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
34db0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34dc0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
34dd0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
34de0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34df0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
34e00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
34e10 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
34e20 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34e30 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
34e40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
34e50 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
34e60 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34e70 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
34e80 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
34e90 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
34ea0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
34eb0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
34ec0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
34ed0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34ee0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
34ef0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
34f00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34f10 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
34f20 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
34f30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34f40 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
34f50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
34f60 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
34f70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34f80 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
34f90 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
34fa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34fb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34fc0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
34fd0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
34fe0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
34ff0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35000 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35010 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
35020 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
35030 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
35040 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35050 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
35060 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
35070 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
35080 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
35090 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
350a0 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
350b0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
350c0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
350d0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
350e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
350f0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35100 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
35110 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
35120 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
35130 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
35140 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
35150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
35160 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
35170 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
35180 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
35190 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
351a0 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
351b0 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
351c0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
351d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
351e0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
351f0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
35200 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
35210 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
35220 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
35230 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
35240 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35250 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
35260 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35270 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
35280 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
35290 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
352a0 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
352b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
352c0 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
352d0 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
352e0 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
352f0 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
35300 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
35310 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
35320 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
35330 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
35340 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
35350 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
35360 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
35370 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
35380 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
35390 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
353a0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
353b0 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
353c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
353d0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
353e0 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
353f0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
35400 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
35410 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
35420 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
35430 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
35440 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
35450 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
35460 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
35470 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
35480 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
35490 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
354a0 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
354b0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
354c0 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
354d0 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
354e0 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
354f0 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
35500 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
35510 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
35520 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
35530 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
35540 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
35550 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
35560 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
35570 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
35580 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
35590 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69   is an applicati
355a0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
355b0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
355c0 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
355d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
355e0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
355f0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
35600 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
35610 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
35620 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
35630 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
35640 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35650 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
35660 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35670 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
35680 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
35690 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
356a0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
356b0 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
356c0 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
356d0 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
356e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
356f0 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
35700 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
35710 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
35720 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
35730 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
35740 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
35750 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35760 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
35770 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
35780 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
35790 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
357a0 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
357b0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
357c0 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
357d0 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
357e0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
357f0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
35800 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
35810 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
35820 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
35830 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
35840 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
35850 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
35860 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
35870 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
35880 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
35890 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
358a0 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
358b0 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
358c0 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
358d0 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
358e0 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
358f0 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
35900 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
35910 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
35920 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
35930 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
35940 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35950 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72  on must always r
35960 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
35970 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
35980 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
35990 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
359a0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
359b0 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
359c0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
359d0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
359e0 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
359f0 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
35a00 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
35a10 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
35a20 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
35a30 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
35a40 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
35a50 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
35a60 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
35a70 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
35a80 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
35a90 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
35aa0 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
35ab0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
35ac0 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
35ad0 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
35ae0 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
35af0 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
35b00 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
35b10 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
35b20 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
35b30 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
35b40 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
35b50 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
35b60 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
35b70 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
35b80 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
35b90 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
35ba0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
35bb0 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
35bc0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
35bd0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
35be0 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
35bf0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
35c00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35c10 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
35c20 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
35c30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
35c40 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
35c50 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
35c60 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
35c70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
35c80 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
35c90 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35ca0 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
35cb0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
35cc0 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
35cd0 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
35ce0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
35cf0 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
35d00 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
35d10 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
35d20 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
35d30 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
35d40 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
35d50 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
35d60 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
35d70 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
35d80 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
35d90 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
35da0 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
35db0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35dc0 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
35dd0 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
35de0 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
35df0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
35e00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
35e10 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
35e20 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
35e30 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
35e40 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
35e50 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
35e60 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
35e70 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
35e80 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
35e90 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
35ea0 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
35eb0 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
35ec0 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
35ed0 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
35ee0 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
35ef0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
35f00 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
35f10 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
35f20 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
35f30 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
35f40 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
35f50 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
35f60 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
35f70 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
35f80 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35f90 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
35fa0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35fb0 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
35fc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35fd0 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
35fe0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
35ff0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
36000 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
36010 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
36020 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
36030 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36040 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36050 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
36060 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36070 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
36080 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
36090 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
360a0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
360b0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
360c0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
360d0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
360e0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
360f0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
36100 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
36110 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36120 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
36130 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
36140 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
36150 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
36160 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
36170 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
36180 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
36190 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
361a0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
361b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
361c0 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
361d0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
361e0 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
361f0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
36200 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
36210 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
36220 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
36230 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
36240 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
36250 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
36260 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
36270 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36280 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
36290 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
362a0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
362b0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
362c0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
362d0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
362e0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
362f0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
36300 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36310 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
36320 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
36330 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
36340 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
36350 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
36360 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
36370 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
36380 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36390 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
363a0 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
363b0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
363c0 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
363d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
363e0 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
363f0 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
36400 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
36410 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
36420 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
36430 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
36440 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
36450 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
36460 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
36470 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
36480 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
36490 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
364a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
364b0 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
364c0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
364d0 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
364e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
364f0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
36500 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
36510 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
36520 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
36530 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
36540 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
36550 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
36560 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
36570 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
36580 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
36590 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
365a0 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
365b0 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
365c0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
365d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
365e0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
365f0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
36600 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
36610 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
36620 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
36630 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
36640 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
36650 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36660 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
36670 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36680 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
36690 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
366a0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
366b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
366c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
366d0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
366e0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
366f0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
36700 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
36710 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
36720 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
36730 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
36740 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
36750 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
36760 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
36770 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
36780 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
36790 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
367a0 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
367b0 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
367c0 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
367d0 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
367e0 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
367f0 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
36800 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
36810 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
36820 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
36830 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
36840 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
36850 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
36860 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
36870 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
36880 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
368a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
368b0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
368c0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
368d0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
368e0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
368f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
36900 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
36910 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
36920 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
36930 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
36940 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
36950 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
36960 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
36970 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  he database */. 
36980 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
36990 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
369a0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
369b0 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
369c0 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
369d0 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
369e0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
369f0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
36a00 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
36a10 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
36a20 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
36a30 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
36a40 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
36a50 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
36a60 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
36a70 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
36a80 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
36a90 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
36aa0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
36ab0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
36ac0 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
36ad0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
36ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36af0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
36b00 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
36b10 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
36b20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
36b30 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
36b40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  ;.int sqlite3_re
36b50 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  key_v2(.  sqlite
36b60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
36b70 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
36b80 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
36b90 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  ed */.  const ch
36ba0 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
36bb0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
36bc0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a  f the database *
36bd0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
36be0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
36bf0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
36c00 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
36c10 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
36c20 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
36c30 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
36c40 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
36c50 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
36c60 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
36c70 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
36c80 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
36c90 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
36ca0 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
36cb0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
36cc0 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
36cd0 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
36ce0 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
36cf0 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
36d00 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
36d10 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
36d20 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
36d30 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
36d40 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
36d50 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
36d60 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
36d70 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
36d80 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
36d90 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
36da0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
36db0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
36dc0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
36dd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
36de0 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
36df0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
36e00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
36e10 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
36e20 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
36e30 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
36e40 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
36e50 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
36e60 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
36e70 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
36e80 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
36e90 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
36ea0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
36eb0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
36ec0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
36ed0 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
36ee0 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
36ef0 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
36f00 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
36f10 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
36f20 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
36f30 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
36f40 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
36f50 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
36f60 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
36f70 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
36f80 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
36f90 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
36fa0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
36fb0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
36fc0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
36fd0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
36fe0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
36ff0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
37000 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
37010 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
37020 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
37030 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
37040 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
37050 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
37060 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
37070 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
37080 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
37090 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
370a0 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
370b0 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
370c0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
370d0 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  phs..*/.int sqli
370e0 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
370f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37100 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
37110 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
37120 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
37130 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
37140 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
37150 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
37160 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
37170 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
37180 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
37190 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
371a0 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
371b0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
371c0 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
371d0 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
371e0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
371f0 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
37200 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
37210 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
37220 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
37230 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
37240 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
37250 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
37260 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
37270 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
37280 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
37290 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
372a0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
372b0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
372c0 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
372d0 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
372e0 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
372f0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
37300 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
37310 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
37320 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
37330 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
37340 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
37350 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
37360 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
37370 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
37380 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
37390 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
373a0 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
373b0 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
373c0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
373d0 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
373e0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
373f0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
37400 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
37410 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
37420 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
37430 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
37440 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
37450 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37460 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
37470 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
37480 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
37490 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
374a0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
374b0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
374c0 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
374d0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
374e0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
374f0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
37500 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
37510 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
37520 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
37530 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
37540 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
37550 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
37560 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
37570 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
37580 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
37590 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
375a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
375b0 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
375c0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
375d0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
375e0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
375f0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
37600 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
37610 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
37620 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
37630 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
37640 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
37650 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
37660 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37670 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
37680 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a  e avoided..**.**
37690 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
376a0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
376b0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
376c0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
376d0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
376e0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
376f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f  [sqlite3_open] o
37700 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
37710 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  v2].  Otherwise,
37720 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
37730 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
37740 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
37750 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
37760 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20   fail.  Here is 
37770 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66  an.** example of
37780 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20   how to do this 
37790 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74  using C++ with t
377a0 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  he Windows Runti
377b0 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  me:.**.** <block
377c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c  quote><pre>.** L
377d0 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57  PCWSTR zPath = W
377e0 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a  indows::Storage:
377f0 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61  :ApplicationData
37800 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26  ::Current->.** &
37810 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72  nbsp;     Tempor
37820 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d  aryFolder->Path-
37830 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72  >Data();.** char
37840 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41   zPathBuf&#91;MA
37850 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b  X_PATH + 1&#93;;
37860 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68  .** memset(zPath
37870 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a  Buf, 0, sizeof(z
37880 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69  PathBuf));.** Wi
37890 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74  deCharToMultiByt
378a0 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50  e(CP_UTF8, 0, zP
378b0 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75  ath, -1, zPathBu
378c0 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  f, sizeof(zPathB
378d0 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  uf),.** &nbsp;  
378e0 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a     NULL, NULL);.
378f0 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
37900 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
37910 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
37920 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
37930 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
37940 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  te>.*/.SQLITE_EX
37950 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
37960 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
37970 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
37980 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
37990 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44  Folder Holding D
379a0 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a  atabase Files.**
379b0 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
379c0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
379d0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
379e0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
379f0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
37a00 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
37a10 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
37a20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73  then all databas
37a30 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69  e files.** speci
37a40 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61  fied with a rela
37a50 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e  tive pathname an
37a60 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63  d created or acc
37a70 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69  essed by.** SQLi
37a80 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
37a90 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73  built-in windows
37aa0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
37ab0 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73  VFS] will be ass
37ac0 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65  umed.** to be re
37ad0 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64  lative to that d
37ae0 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20  irectory.)^ ^If 
37af0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
37b00 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
37b10 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
37b20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c  assumes that all
37b30 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
37b40 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74  specified.** wit
37b50 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  h a relative pat
37b60 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69  hname are relati
37b70 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ve to the curren
37b80 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66  t directory.** f
37b90 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20  or the process. 
37ba0 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77   Only the window
37bb0 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20  s VFS makes use 
37bc0 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a  of this global.*
37bd0 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69  * variable; it i
37be0 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65  s ignored by the
37bf0 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   unix VFS..**.**
37c00 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61   Changing the va
37c10 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69  lue of this vari
37c20 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74  able while a dat
37c30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37c40 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20   is.** open can 
37c50 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72  result in a corr
37c60 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  upt database..**
37c70 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
37c80 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
37c90 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
37ca0 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
37cb0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
37cc0 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
37cd0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
37ce0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
37cf0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
37d00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37d10 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
37d20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
37d30 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
37d40 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
37d50 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
37d60 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
37d70 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
37d80 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
37d90 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
37da0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
37db0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
37dc0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
37dd0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
37de0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
37df0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
37e00 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
37e10 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
37e20 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  The [data_store_
37e30 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
37e40 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
37e50 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
37e60 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
37e70 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
37e80 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
37e90 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
37ea0 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
37eb0 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
37ec0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
37ed0 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
37ee0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
37ef0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
37f00 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
37f10 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
37f20 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
37f30 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
37f40 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
37f50 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
37f60 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
37f70 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
37f80 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
37f90 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
37fa0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
37fb0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
37fc0 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
37fd0 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
37fe0 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
37ff0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
38000 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
38010 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
38020 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
38030 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
38040 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
38050 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
38060 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
38070 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
38080 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f  te3_data_directo
38090 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
380a0 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
380b0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
380c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
380d0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
380e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
380f0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
38100 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
38110 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
38120 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
38130 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
38140 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
38150 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
38160 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
38170 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
38180 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
38190 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
381a0 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
381b0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
381c0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
381d0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  ement..** ^Autoc
381e0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
381f0 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
38200 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
38210 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
38220 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
38230 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
38240 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
38250 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
38260 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
38270 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
38280 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
38290 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
382a0 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
382b0 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
382c0 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
382d0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
382e0 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
382f0 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
38300 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
38310 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
38320 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
38330 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
38340 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
38350 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
38360 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
38370 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
38380 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
38390 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
383a0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
383b0 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
383c0 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
383d0 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
383e0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
383f0 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
38400 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
38410 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
38420 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
38430 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
38440 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
38450 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
38460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38470 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
38480 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
38490 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
384a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
384b0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
384c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
384d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
384e0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
384f0 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
38500 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
38510 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
38520 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
38530 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
38540 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
38550 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
38560 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
38570 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
38580 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
38590 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
385a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
385b0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
385c0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
385d0 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
385e0 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
385f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
38600 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
38610 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
38620 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
38630 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
38640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
38650 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e 61  eturn The Filena
38660 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61 73  me For A Databas
38670 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
38680 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
38690 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29  db_filename(D,N)
386a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
386b0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
386c0 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73  a filename.** as
386d0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 64 61  sociated with da
386e0 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e  tabase N of conn
386f0 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20  ection D.  ^The 
38700 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
38710 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e 61  le.** has the na
38720 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20 74  me "main".  If t
38730 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61 63  here is no attac
38740 68 65 64 20 64 61 74 61 62 61 73 65 20 4e 20 6f  hed database N o
38750 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
38760 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  * connection D, 
38770 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 20 4e  or if database N
38780 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79 20   is a temporary 
38790 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  or in-memory dat
387a0 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61  abase, then.** a
387b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
387c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
387d0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 72   ^The filename r
387e0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
387f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20  function is the 
38800 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a  output of the.**
38810 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d   xFullPathname m
38820 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56 46  ethod of the [V