/ Hex Artifact Content
Login

Artifact 4373b4a913ea460d91a9a4a54906ee18b350d573:


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 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5680: 4e 4f 44 42 20 20 20 20 20 20 20 20 20 20 20 20  NODB            
5690: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
56a0: 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (27<<8)).#defi
56b0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
56c0: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
56d0: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56e0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56f0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
5700: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
5710: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
5720: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
5730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5740: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5750: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5760: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5780: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5790: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
57a0: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
57b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
57c0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
57d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57e0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5800: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5810: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5820: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5830: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5840: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5850: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5860: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5880: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5890: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
58a0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
58b0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
58c0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
58d0: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58f0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5900: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5910: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
5920: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5930: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5940: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5950: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5960: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5970: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
5990: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
59a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
59b0: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
59d0: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
59f0: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
5a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5a10: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
5a20: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
5a30: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
5a40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
5a60: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
5a70: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5a80: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5a90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5aa0: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
5ab0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ac0: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
5ad0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ae0: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
5af0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b00: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
5b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b20: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
5b30: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
5b40: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
5b50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b60: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
5b70: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
5b80: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b90: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5ba0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bb0: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5bc0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bd0: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
5be0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bf0: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
5c00: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c10: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
5c20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c30: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
5c40: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5c50: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
5c60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c70: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5c80: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
5c90: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
5ca0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cb0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5cc0: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
5cd0: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
5ce0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cf0: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
5d00: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
5d10: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
5d20: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5d30: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5d40: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5d50: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5d60: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5d70: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5d80: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5d90: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5da0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5db0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5dc0: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5dd0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5de0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5df0: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5e00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e10: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5e20: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5e30: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e40: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e60: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
5e70: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
5e80: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e90: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5ea0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5eb0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
5ec0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5ed0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5ee0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5ef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f00: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5f10: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5f20: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f40: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5f50: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5f60: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f80: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
5f90: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
5fa0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5fb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fc0: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5fd0: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
5fe0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5ff0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6010: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20  PEN_MEMORY      
6020: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20       0x00000080 
6030: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6040: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6060: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
6070: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
6080: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60a0: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
60b0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
60c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
60d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60e0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
60f0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
6100: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6120: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
6130: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
6140: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6160: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
6170: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
6180: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61a0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
61b0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
61c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
61d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61e0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
61f0: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
6200: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6220: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
6230: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
6240: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6250: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6260: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6270: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
6280: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
6290: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
62a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
62b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
62c0: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
62d0: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
62e0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
62f0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6310: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
6320: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
6330: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6340: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6350: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6360: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
6370: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
6380: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6390: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 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 30 78 30 30 46 30 30 30 30 30        0x00F00000
63c0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
63d0: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
63e0: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
63f0: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
6400: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
6410: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
6420: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
6430: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
6440: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6450: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
6460: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
6470: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
6480: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
6490: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
64a0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
64b0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
64c0: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
64d0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
64e0: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
64f0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
6500: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6510: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6520: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6530: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6540: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6550: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6560: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6570: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6580: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6590: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
65a0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
65b0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
65c0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
65d0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
65e0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
65f0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6600: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6610: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6620: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6630: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6640: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6650: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6660: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6670: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6680: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
6690: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
66a0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
66b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
66c0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
66d0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
66e0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
66f0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
6700: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
6710: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
6720: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
6730: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6740: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6750: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
6760: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
6770: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
6780: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
6790: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
67a0: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
67b0: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
67c0: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
67d0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
67e0: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
67f0: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
6800: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
6810: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
6820: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
6830: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
6840: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6850: 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  nged.  The SQLIT
6860: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6870: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a  BLE_WHEN_OPEN.**
6880: 20 61 6e 64 20 53 51 4c 49 54 45 5f 49 4f 43 41   and SQLITE_IOCA
6890: 50 5f 55 4e 4d 4f 56 41 42 4c 45 5f 57 48 45 4e  P_UNMOVABLE_WHEN
68a0: 5f 4f 50 45 4e 20 66 6c 61 67 73 20 69 6e 64 69  _OPEN flags indi
68b0: 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65  cate that a file
68c0: 20 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 64   .** cannot be d
68d0: 65 6c 65 74 65 64 20 6f 72 20 72 65 6e 61 6d 65  eleted or rename
68e0: 64 20 77 68 65 6e 20 6f 70 65 6e 2c 20 72 65 73  d when open, res
68f0: 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2f 0a 23 64  pectively..*/.#d
6900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6910: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
6920: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6930: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
6940: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6950: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
6960: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6970: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6980: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
6990: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
69a0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
69b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
69c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
69d0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
69e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69f0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6a00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a20: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
6a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a40: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
6a50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a60: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
6a70: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
6a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a90: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
6aa0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6ab0: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
6ac0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ad0: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
6ae0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6af0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b00: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
6b10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b20: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
6b30: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6b40: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
6b50: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
6b60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b70: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6b80: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
6b90: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6ba0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6bb0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
6bc0: 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65  00001000.#define
6bd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6be0: 4d 4f 56 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  MOVABLE_WHEN_OPE
6bf0: 4e 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a  N    0x00002000.
6c00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c10: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
6c20: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6c30: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6c40: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6c50: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6c60: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
6c70: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
6c80: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
6c90: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
6ca0: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
6cb0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6cc0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
6cd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6ce0: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
6cf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d00: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
6d10: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6d20: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6d30: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6d40: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
6d50: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
6d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6d70: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
6d80: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6d90: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
6da0: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
6db0: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
6dc0: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
6dd0: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
6de0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6df0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
6e00: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
6e10: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
6e20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6e30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
6e40: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
6e50: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
6e60: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
6e70: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
6e80: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
6e90: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
6ea0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
6eb0: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
6ec0: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
6ed0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
6ee0: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
6ef0: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
6f00: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
6f10: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
6f20: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6f30: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
6f40: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6f50: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
6f60: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
6f70: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
6f80: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6f90: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
6fa0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
6fb0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6fc0: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6fd0: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
6fe0: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
6ff0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7000: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7010: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
7020: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
7030: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
7040: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
7050: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
7060: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
7070: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
7080: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
7090: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
70a0: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
70b0: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
70c0: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
70d0: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
70e0: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
70f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7100: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7110: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
7120: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
7130: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
7140: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
7150: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
7160: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
7170: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
7180: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
7190: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
71a0: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
71b0: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
71c0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
71d0: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
71e0: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
71f0: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
7200: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7210: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7220: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
7230: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
7240: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
7250: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
7260: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
7270: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
7280: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
7290: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
72a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
72b0: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
72c0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
72d0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
72e0: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
72f0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7300: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
7310: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
7320: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7330: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
7340: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
7350: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7360: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
7370: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
7380: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
7390: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
73a0: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
73b0: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
73c0: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
73d0: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
73e0: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
73f0: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
7400: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
7410: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
7420: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
7430: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
7440: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
7450: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
7460: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7470: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
7480: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
7490: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
74a0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
74b0: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
74c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
74d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
74e0: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
74f0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7500: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
7510: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7520: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
7530: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
7540: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
7550: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7560: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7570: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
7580: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
7590: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
75a0: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
75b0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
75c0: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
75d0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
75e0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
75f0: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
7600: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
7610: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7620: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
7630: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7640: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
7650: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
7660: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
7670: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
7680: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
7690: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
76a0: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
76b0: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
76c0: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
76d0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
76e0: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
76f0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7700: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
7710: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7720: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7730: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
7740: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
7750: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
7760: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
7770: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
7780: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
7790: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
77a0: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
77b0: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
77c0: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
77d0: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
77e0: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
77f0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
7800: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
7810: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
7820: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7830: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
7840: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7850: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7860: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
7870: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
7880: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
7890: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
78a0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
78b0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
78c0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
78d0: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
78e0: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
78f0: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
7900: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
7910: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7920: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
7930: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7940: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
7950: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
7960: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
7970: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
7980: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
7990: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
79a0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
79b0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
79c0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
79d0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
79e0: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
79f0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7a00: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
7a10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7a20: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
7a30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a40: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
7a50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a60: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
7a70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7a80: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
7a90: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
7aa0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
7ab0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
7ac0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
7ad0: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
7ae0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7af0: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
7b00: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
7b10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7b20: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7b30: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7b40: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
7b50: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
7b60: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
7b70: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
7b80: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
7b90: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
7ba0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
7bb0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
7bc0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
7bd0: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
7be0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7bf0: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
7c00: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
7c10: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
7c20: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7c30: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7c40: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
7c50: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
7c60: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7c70: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
7c80: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
7c90: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
7ca0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
7cb0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
7cc0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
7cd0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
7ce0: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
7cf0: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
7d00: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
7d10: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
7d20: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7d30: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7d40: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
7d50: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
7d60: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
7d70: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
7d80: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
7d90: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
7da0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
7db0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
7dc0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
7dd0: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
7de0: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
7df0: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
7e00: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
7e10: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
7e20: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
7e30: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
7e40: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
7e50: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
7e60: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
7e70: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
7e80: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
7e90: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7ea0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
7eb0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
7ec0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
7ed0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
7ee0: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
7ef0: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
7f00: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
7f10: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
7f20: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
7f30: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
7f40: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
7f50: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
7f60: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
7f70: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
7f80: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
7f90: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
7fa0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
7fb0: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
7fc0: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
7fd0: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
7fe0: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
7ff0: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
8000: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
8010: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
8020: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
8030: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
8040: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
8050: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
8060: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
8070: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
8080: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
8090: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
80a0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
80b0: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
80c0: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
80d0: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
80e0: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
80f0: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
8100: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8110: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
8120: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8130: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
8140: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8150: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
8160: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8170: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
8180: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8190: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
81a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
81b0: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
81c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
81d0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
81e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
81f0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
8200: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8210: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
8220: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8230: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
8240: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
8250: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
8260: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
8270: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
8280: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
8290: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
82a0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
82b0: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
82c0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
82d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
82e0: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
82f0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
8300: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
8310: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
8320: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
8330: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
8340: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
8350: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
8360: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
8370: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
8380: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8390: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
83a0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
83b0: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
83c0: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
83d0: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
83e0: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
83f0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
8400: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
8410: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
8420: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
8430: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8440: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
8450: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
8460: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
8470: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
8480: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
8490: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
84a0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
84b0: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
84c0: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
84d0: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
84e0: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
84f0: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
8500: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
8510: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
8520: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
8530: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
8540: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
8550: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
8560: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
8570: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
8580: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8590: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
85a0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
85b0: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
85c0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
85d0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
85e0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
85f0: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
8600: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
8610: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
8620: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
8630: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
8640: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8650: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
8660: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
8670: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8680: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8690: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
86a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
86b0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
86c0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
86d0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
86e0: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
86f0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8700: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
8710: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
8720: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8730: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
8740: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
8750: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8760: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
8770: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
8780: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8790: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
87a0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
87b0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
87c0: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
87d0: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
87e0: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
87f0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
8800: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
8810: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8820: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
8830: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
8840: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8850: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
8860: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8870: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
8880: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
8890: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
88a0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
88b0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
88c0: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
88d0: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
88e0: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
88f0: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
8900: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
8910: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8920: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
8930: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
8940: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
8950: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
8960: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
8970: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
8980: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
8990: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
89a0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
89b0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
89c0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74   */.  int (*xFet
89d0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
89e0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
89f0: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74   iOfst, int iAmt
8a00: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20  , void **pp);.  
8a10: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28  int (*xUnfetch)(
8a20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8a40: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20  st, void *p);.  
8a50: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8a60: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8a70: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a  ersion 3 */.  /*
8a80: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
8a90: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
8aa0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
8ab0: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
8ac0: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
8ad0: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
8ae0: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
8af0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8b00: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8b10: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8b20: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8b30: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8b40: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8b50: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
8b60: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8b70: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
8b80: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
8b90: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8ba0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8bb0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8bc0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8bd0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8be0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8bf0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8c00: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8c10: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8c20: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8c30: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8c50: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8c60: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8c70: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8c80: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8c90: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8ca0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8cb0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8cc0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8cd0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8ce0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8cf0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8d00: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8d10: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8d20: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8d30: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8d40: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8d50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8d60: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8d70: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8d80: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8d90: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
8da0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8db0: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8dc0: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8dd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8de0: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8df0: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8e00: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8e10: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8e20: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8e30: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8e40: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8e50: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8e60: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8e70: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8e80: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8e90: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8ea0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8eb0: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8ec0: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8ed0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8ee0: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8ef0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8f00: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8f10: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8f20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8f30: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8f40: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
8f50: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
8f60: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
8f70: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
8f80: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
8f90: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
8fa0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8fb0: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8fc0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8fd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8fe0: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8ff0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
9000: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
9010: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
9020: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
9030: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
9040: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
9050: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
9060: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
9070: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
9080: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
9090: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
90a0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
90b0: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
90c0: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
90d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
90e0: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
90f0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9100: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9110: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9130: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9140: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9150: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9160: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9170: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9180: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
9190: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
91a0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
91b0: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
91c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
91d0: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
91e0: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
91f0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
9200: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9210: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
9220: 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65  ITTED]].** ^(The
9230: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
9240: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
9250: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9260: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
9270: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
9280: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
9290: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
92a0: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
92b0: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
92c0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
92d0: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
92e0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
92f0: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
9300: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
9310: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
9320: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
9330: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
9340: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
9350: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9360: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9370: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
9380: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
9390: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
93a0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
93b0: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
93c0: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
93d0: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
93e0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
93f0: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
9400: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9410: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
9420: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9430: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9440: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
9450: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9460: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
9470: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9480: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9490: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
94a0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
94b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
94c0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
94d0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
94e0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
94f0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9500: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9510: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9520: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9530: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9540: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9550: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9560: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9570: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9580: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9590: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
95a0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
95b0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
95c0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
95d0: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
95e0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
95f0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9600: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9610: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9620: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9630: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9640: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9650: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9660: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9670: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9680: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9690: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
96a0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
96b0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
96c0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
96d0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
96e0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
96f0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9700: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9710: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9730: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9740: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9750: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9760: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9770: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9780: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9790: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
97a0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
97b0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
97c0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
97d0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
97e0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
97f0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9800: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9810: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9820: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9830: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9840: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9850: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9860: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9870: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9880: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9890: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
98a0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
98b0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
98c0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
98d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
98e0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
98f0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9910: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9920: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9930: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9940: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9950: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9960: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9970: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9980: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9990: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
99a0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
99b0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
99c0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
99d0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
99e0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
99f0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9a00: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9a10: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9a20: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9a30: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9a40: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9a50: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9a60: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9a70: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9a80: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9a90: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9aa0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9ab0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9ac0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9ad0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9ae0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9af0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9b00: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9b10: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9b20: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9b30: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9b40: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9b50: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9b60: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9b70: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9b80: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9b90: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9ba0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9bb0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9bc0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9bd0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9be0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9bf0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9c00: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9c10: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9c20: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9c30: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9c40: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9c50: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9c60: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9c70: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9c80: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9c90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ca0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9cb0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9cc0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9cd0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9ce0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9cf0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9d00: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9d10: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9d20: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9d30: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9d40: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
9d50: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
9d60: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
9d70: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9d80: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
9d90: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
9da0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9db0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9dc0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
9dd0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9de0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
9df0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
9e00: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
9e10: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
9e20: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
9e30: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
9e40: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9e50: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
9e60: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
9e70: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9e80: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9e90: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9ea0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9eb0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
9ec0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
9ed0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9ee0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
9ef0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
9f00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9f10: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9f20: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
9f30: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
9f40: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
9f50: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
9f60: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
9f70: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
9f80: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
9f90: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
9fa0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9fb0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
9fc0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
9fd0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
9fe0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
9ff0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a000: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a010: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a020: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a030: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a040: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a050: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a060: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a070: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a080: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a090: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a0a0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a0b0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a0c0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a0d0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a0e0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a0f0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a100: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a110: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a120: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a130: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a140: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a150: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a160: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a170: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a180: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a190: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a1a0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a1b0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a1c0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a1d0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a1e0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a1f0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a200: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a210: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a220: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a230: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a240: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a250: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a260: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a270: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a280: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a290: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a2a0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a2b0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a2c0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a2d0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a2e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a2f0: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a300: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a310: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a320: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a330: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a340: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a350: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a360: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a370: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a380: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a390: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a3a0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a3b0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a3c0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a3d0: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a3e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a3f0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a400: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a410: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a420: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a430: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a440: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a450: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a460: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a470: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a480: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a490: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a4a0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a4b0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a4c0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a4d0: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a4e0: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a4f0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a500: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a510: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a520: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a530: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a540: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a550: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a560: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a570: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a580: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a590: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a5a0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a5b0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a5c0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a5d0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a5e0: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a5f0: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a600: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a610: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a620: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a630: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a640: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a650: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a660: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a670: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a680: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a690: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a6a0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a6b0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a6c0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a6d0: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a6e0: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a6f0: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a700: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a710: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a720: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a730: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a740: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a750: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a760: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a770: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a780: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a790: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a7a0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a7b0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a7c0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
a7d0: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
a7e0: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
a7f0: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
a800: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
a810: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
a820: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
a830: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a840: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a850: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
a860: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
a870: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
a880: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
a890: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
a8a0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
a8b0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
a8c0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
a8d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a8e0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
a8f0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a900: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
a910: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
a920: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
a930: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
a940: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
a950: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
a960: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
a970: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
a980: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
a990: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
a9a0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
a9b0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
a9c0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
a9d0: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
a9e0: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
a9f0: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
aa00: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
aa10: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
aa20: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
aa30: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
aa40: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
aa50: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
aa60: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
aa70: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
aa80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
aa90: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
aaa0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
aab0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
aac0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
aad0: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
aae0: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
aaf0: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
ab00: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
ab10: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
ab20: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
ab30: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
ab40: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
ab50: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
ab60: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
ab70: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
ab80: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
ab90: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
aba0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
abb0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
abc0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
abd0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
abe0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
abf0: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
ac00: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
ac10: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
ac20: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ac30: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
ac40: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ac50: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ac60: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
ac70: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
ac80: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
ac90: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
aca0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
acb0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
acc0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
acd0: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
ace0: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
acf0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
ad00: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
ad10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
ad20: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
ad30: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
ad40: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
ad50: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
ad60: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
ad70: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
ad80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ad90: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
ada0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
adb0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
adc0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
add0: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
ade0: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
adf0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
ae00: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
ae10: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
ae20: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
ae30: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
ae40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
ae50: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
ae60: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
ae70: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
ae80: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
ae90: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
aea0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
aeb0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
aec0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
aed0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
aee0: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
aef0: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
af00: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
af10: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
af20: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
af30: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
af40: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
af50: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
af60: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
af70: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
af80: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
af90: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
afa0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
afb0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
afc0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
afd0: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
afe0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
aff0: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b000: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b010: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b020: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b030: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b040: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b050: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b060: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b070: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b080: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b090: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b0a0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b0b0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b0c0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b0d0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b0e0: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b0f0: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b100: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b110: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b120: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b130: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b140: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b150: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b160: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b170: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b180: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b190: 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  **.** </ul>.*/.#
b1a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b1b0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
b1c0: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
b1d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
b1e0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
b1f0: 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
b200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
b210: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
b220: 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
b230: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
b240: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
b250: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
b260: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b270: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
b280: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
b290: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
b2a0: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
b2b0: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
b2c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
b2d0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
b2e0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
b2f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
b300: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
b310: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
b320: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
b330: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
b340: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
b350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
b360: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
b370: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
b380: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
b390: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
b3a0: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
b3b0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
b3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b3d0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
b3e0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
b3f0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
b400: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
b410: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
b420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
b430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b440: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b450: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
b460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b470: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
b480: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
b490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b4a0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
b4b0: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
b4c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b4d0: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
b4e0: 20 20 20 20 20 20 20 20 20 20 31 39 0a 0a 2f 2a            19../*
b4f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
b500: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
b510: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
b520: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
b530: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
b540: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
b550: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
b560: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
b570: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
b580: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
b590: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
b5a0: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
b5b0: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
b5c0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
b5d0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
b5e0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
b5f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
b600: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
b610: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
b620: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
b630: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
b640: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
b650: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
b660: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
b670: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
b680: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
b690: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
b6a0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
b6b0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
b6c0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
b6d0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
b6e0: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
b6f0: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
b700: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
b710: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
b720: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
b730: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
b740: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
b750: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
b760: 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20  m".  See.** the 
b770: 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d  [VFS | VFS docum
b780: 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75  entation] for fu
b790: 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f  rther informatio
b7a0: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  n..**.** The val
b7b0: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
b7c0: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
b7d0: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
b7e0: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
b7f0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
b800: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
b810: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
b820: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
b830: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
b840: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
b850: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
b860: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
b870: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
b880: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
b890: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
b8a0: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
b8b0: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
b8c0: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
b8d0: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
b8e0: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
b8f0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
b900: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
b910: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
b920: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
b930: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
b940: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
b950: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
b960: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
b970: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
b980: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
b990: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
b9a0: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
b9b0: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
b9c0: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
b9d0: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
b9e0: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
b9f0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
ba00: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
ba10: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
ba20: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
ba30: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
ba40: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
ba50: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
ba60: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
ba70: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
ba80: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
ba90: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
baa0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
bab0: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
bac0: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
bad0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
bae0: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
baf0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
bb00: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
bb10: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
bb20: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
bb30: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
bb40: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
bb50: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
bb60: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
bb70: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
bb80: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
bb90: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
bba0: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
bbb0: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
bbc0: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
bbd0: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
bbe0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
bbf0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
bc00: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
bc10: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
bc20: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
bc30: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
bc40: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
bc50: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
bc60: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
bc70: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
bc80: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
bc90: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
bca0: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
bcb0: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
bcc0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
bcd0: 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e  vfs.xOpen]].** ^
bce0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
bcf0: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
bd00: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
bd10: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
bd20: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
bd30: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
bd40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
bd50: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
bd60: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
bd70: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
bd80: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
bd90: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
bda0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
bdb0: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
bdc0: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
bdd0: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
bde0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
bdf0: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61  ore than.** 11 a
be00: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
be10: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
be20: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
be30: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
be40: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
be50: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
be60: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
be70: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
be80: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
be90: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
bea0: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
beb0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
bec0: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
bed0: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
bee0: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
bef0: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
bf00: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
bf10: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
bf20: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
bf30: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
bf40: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
bf50: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
bf60: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
bf70: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
bf80: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
bf90: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
bfa0: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
bfb0: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
bfc0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
bfd0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
bfe0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
bff0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
c000: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
c010: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
c020: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
c030: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
c040: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
c050: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
c060: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
c070: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c080: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
c090: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
c0a0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c0b0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
c0c0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
c0d0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
c0e0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
c0f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
c100: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
c110: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
c120: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
c130: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
c140: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
c150: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
c160: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
c170: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
c180: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
c190: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
c1a0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
c1b0: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
c1c0: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
c1d0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
c1e0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
c1f0: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
c200: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
c210: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
c220: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
c230: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c240: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
c250: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c260: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
c270: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c280: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
c290: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c2a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
c2b0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c2c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
c2d0: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
c2e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
c2f0: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
c300: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c310: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
c320: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c330: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
c340: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
c350: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
c360: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
c370: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
c380: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
c390: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
c3a0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
c3b0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
c3c0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
c3d0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
c3e0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
c3f0: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
c400: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
c410: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
c420: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
c430: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
c440: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
c450: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
c460: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
c470: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
c480: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
c490: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
c4a0: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
c4b0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
c4c0: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
c4d0: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
c4e0: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
c4f0: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
c500: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
c510: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
c520: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
c530: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
c540: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
c550: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
c560: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
c570: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
c580: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
c590: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
c5a0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
c5b0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
c5c0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c5d0: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
c5e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
c5f0: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
c600: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
c610: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
c620: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
c630: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
c640: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
c650: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
c660: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
c670: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
c680: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
c690: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
c6a0: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
c6b0: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
c6c0: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
c6d0: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
c6e0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
c6f0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
c700: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
c710: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
c720: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
c730: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
c740: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
c750: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
c760: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
c770: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
c780: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
c790: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
c7a0: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
c7b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
c7c0: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
c7d0: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
c7e0: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
c7f0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
c800: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
c810: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
c820: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
c830: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
c840: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
c850: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
c860: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
c870: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
c880: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
c890: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
c8a0: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
c8b0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
c8c0: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
c8d0: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
c8e0: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
c8f0: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
c900: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
c910: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
c920: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
c930: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
c940: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
c950: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
c960: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
c970: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
c980: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
c990: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
c9a0: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
c9b0: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
c9c0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
c9d0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
c9e0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
c9f0: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
ca00: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
ca10: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
ca20: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
ca30: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
ca40: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
ca50: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
ca60: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
ca70: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
ca80: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
ca90: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
caa0: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
cab0: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
cac0: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
cad0: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
cae0: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
caf0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
cb00: 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a  3_vfs.xAccess]].
cb10: 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72  ** ^The flags ar
cb20: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
cb30: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
cb40: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
cb50: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
cb60: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
cb70: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
cb80: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
cb90: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
cba0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
cbb0: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
cbc0: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
cbd0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
cbe0: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
cbf0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
cc00: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
cc10: 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61  e.   The file ca
cc20: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
cc30: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ory..**.** ^SQLi
cc40: 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61  te will always a
cc50: 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74  llocate at least
cc60: 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79   mxPathname+1 by
cc70: 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f  tes for the.** o
cc80: 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75  utput buffer xFu
cc90: 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65  llPathname.  The
cca0: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
ccb0: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
ccc0: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
ccd0: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
cce0: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
ccf0: 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75  ds. If the outpu
cd00: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e  t buffer.** is n
cd10: 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c  ot large enough,
cd20: 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
cd30: 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  N] should be ret
cd40: 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69  urned. Since thi
cd50: 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20  s is.** handled 
cd60: 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  as a fatal error
cd70: 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20   by SQLite, vfs 
cd80: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
cd90: 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a  should endeavor.
cda0: 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ** to prevent th
cdb0: 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78  is by setting mx
cdc0: 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75  Pathname to a su
cdd0: 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65  fficiently large
cde0: 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   value..**.** Th
cdf0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c  e xRandomness(),
ce00: 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72   xSleep(), xCurr
ce10: 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78  entTime(), and x
ce20: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
ce30: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
ce40: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
ce50: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
ce60: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
ce70: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
ce80: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
ce90: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
cea0: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
ceb0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
cec0: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
ced0: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
cee0: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
cef0: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
cf00: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
cf10: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
cf20: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
cf30: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
cf40: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
cf50: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
cf60: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
cf70: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
cf80: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
cf90: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
cfa0: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
cfb0: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
cfc0: 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20  ds given.  ^The 
cfd0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
cfe0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
cff0: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
d000: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
d010: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
d020: 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74  me as.** a float
d030: 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e  ing point value.
d040: 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e  .** ^The xCurren
d050: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
d060: 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20  hod returns, as 
d070: 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20  an integer, the 
d080: 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75  Julian.** Day Nu
d090: 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20  mber multiplied 
d0a0: 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65  by 86400000 (the
d0b0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
d0c0: 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61  seconds in .** a
d0d0: 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20   24-hour day).  
d0e0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
d0f0: 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e   use the xCurren
d100: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
d110: 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63  hod to get the c
d120: 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61  urrent.** date a
d130: 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20  nd time if that 
d140: 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61  method is availa
d150: 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e  ble (if iVersion
d160: 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65   is 2 or .** gre
d170: 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e  ater and the fun
d180: 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
d190: 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77   not NULL) and w
d1a0: 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a  ill fall back.**
d1b0: 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65   to xCurrentTime
d1c0: 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69  () if xCurrentTi
d1d0: 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61  meInt64() is una
d1e0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  vailable..**.** 
d1f0: 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43  ^The xSetSystemC
d200: 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65  all(), xGetSyste
d210: 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65  mCall(), and xNe
d220: 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69  stSystemCall() i
d230: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65  nterfaces.** are
d240: 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65   not used by the
d250: 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54   SQLite core.  T
d260: 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e  hese optional in
d270: 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
d280: 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65  vided.** by some
d290: 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69   VFSes to facili
d2a0: 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20  tate testing of 
d2b0: 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79  the VFS code. By
d2c0: 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20   overriding .** 
d2d0: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74  system calls wit
d2e0: 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65  h functions unde
d2f0: 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61  r its control, a
d300: 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61   test program ca
d310: 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61  n.** simulate fa
d320: 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63  ults and error c
d330: 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77  onditions that w
d340: 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62  ould otherwise b
d350: 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f  e difficult.** o
d360: 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20  r impossible to 
d370: 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74  induce.  The set
d380: 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73   of system calls
d390: 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
d3a0: 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65  rridden.** varie
d3b0: 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74  s from one VFS t
d3c0: 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66  o another, and f
d3d0: 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20  rom one version 
d3e0: 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  of the same VFS 
d3f0: 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20  to the.** next. 
d400: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
d410: 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74  at use these int
d420: 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20  erfaces must be 
d430: 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79  prepared for any
d440: 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68  .** or all of th
d450: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74  ese interfaces t
d460: 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72  o be NULL or for
d470: 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20   their behavior 
d480: 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f  to change.** fro
d490: 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f  m one release to
d4a0: 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c   the next.  Appl
d4b0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f  ications must no
d4c0: 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63  t attempt to acc
d4d0: 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68  ess.** any of th
d4e0: 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74  ese methods if t
d4f0: 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74  he iVersion of t
d500: 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74  he VFS is less t
d510: 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65  han 3..*/.typede
d520: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
d530: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
d540: 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  ;.typedef void (
d550: 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c  *sqlite3_syscall
d560: 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72  _ptr)(void);.str
d570: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
d580: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
d590: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
d5a0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
d5b0: 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e  n number (curren
d5c0: 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20  tly 3) */.  int 
d5d0: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
d5e0: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
d5f0: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
d600: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
d610: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
d620: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
d630: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
d640: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
d650: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
d660: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
d670: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
d680: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d690: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
d6a0: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
d6b0: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
d6c0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
d6d0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
d6e0: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
d6f0: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
d700: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
d710: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
d720: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d730: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
d740: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
d750: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
d760: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
d770: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
d780: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d790: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d7a0: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
d7b0: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
d7c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d7d0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d7e0: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
d7f0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
d800: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
d810: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
d820: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d830: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
d840: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
d850: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
d860: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
d870: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
d880: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
d890: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
d8a0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
d8b0: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
d8c0: 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
d8d0: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
d8e0: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
d8f0: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
d900: 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
d910: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
d920: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
d930: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
d940: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d950: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
d960: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
d970: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
d980: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
d990: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
d9a0: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
d9b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
d9c0: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
d9d0: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
d9e0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
d9f0: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20   char *);.  /*. 
da00: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
da10: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
da20: 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71  sion 1 of the sq
da30: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a  lite_vfs object.
da40: 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e    ** definition.
da50: 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c    Those that fol
da60: 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e  low are added in
da70: 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61   version 2 or la
da80: 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  ter.  */.  int (
da90: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74  *xCurrentTimeInt
daa0: 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  64)(sqlite3_vfs*
dab0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a  , sqlite3_int64*
dac0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
dad0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
dae0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
daf0: 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71   and 2 of the sq
db00: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
db10: 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f  .  ** Those belo
db20: 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f  w are for versio
db30: 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e  n 3 and greater.
db40: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  .  */.  int (*xS
db50: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
db60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
db70: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
db80: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
db90: 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73  tr);.  sqlite3_s
dba0: 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65  yscall_ptr (*xGe
dbb0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
dbc0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dbd0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
dbe0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78   const char *(*x
dbf0: 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  NextSystemCall)(
dc00: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
dc10: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
dc20: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
dc30: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
dc40: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
dc50: 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65  through 3 of the
dc60: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
dc70: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
dc80: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
dc90: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
dca0: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
dcb0: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
dcc0: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
dcd0: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
dce0: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
dcf0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
dd00: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
dd10: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
dd20: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
dd30: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
dd40: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
dd50: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
dd60: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
dd70: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
dd80: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
dd90: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
dda0: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
ddb0: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
ddc0: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
ddd0: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
dde0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
ddf0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
de00: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
de10: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
de20: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
de30: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
de40: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
de50: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
de60: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
de70: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
de80: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
de90: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
dea0: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
deb0: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
dec0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
ded0: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
dee0: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
def0: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
df00: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
df10: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
df20: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
df30: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
df40: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
df50: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
df60: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
df70: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
df80: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
df90: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
dfa0: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
dfb0: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
dfc0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
dfd0: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
dfe0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
dff0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
e000: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
e010: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
e020: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
e030: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
e040: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
e050: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
e060: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
e070: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
e080: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
e090: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
e0a0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
e0b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e0c0: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
e0d0: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
e0e0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
e0f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e100: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
e110: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
e120: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
e130: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
e140: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
e150: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
e160: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
e170: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
e180: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
e190: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
e1a0: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
e1b0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
e1c0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
e1d0: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
e1e0: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
e1f0: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
e200: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
e210: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
e220: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
e230: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
e240: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e250: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
e260: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
e270: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
e280: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
e290: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
e2a0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
e2b0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
e2c0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
e2d0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
e2e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e2f0: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
e300: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
e310: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
e320: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
e330: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
e340: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
e350: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
e360: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
e370: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
e380: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
e390: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
e3a0: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
e3b0: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
e3c0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
e3d0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
e3e0: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
e3f0: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
e400: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
e410: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
e420: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
e430: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
e440: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
e450: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
e460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
e470: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
e480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e490: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
e4a0: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
e4b0: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
e4c0: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
e4d0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
e4e0: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
e4f0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
e500: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
e510: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
e520: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
e530: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
e540: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
e550: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
e560: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
e570: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
e580: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
e590: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
e5a0: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
e5b0: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
e5c0: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
e5d0: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
e5e0: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
e5f0: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
e600: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
e610: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
e620: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
e630: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
e640: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
e650: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
e660: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
e670: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
e680: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
e690: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
e6a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
e6b0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
e6c0: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
e6d0: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
e6e0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
e6f0: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
e700: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
e710: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
e720: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
e730: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
e740: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
e750: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
e760: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
e770: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
e780: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
e790: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
e7a0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
e7b0: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
e7c0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
e7d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e7e0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
e7f0: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
e800: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
e810: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
e820: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
e830: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e840: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
e850: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
e860: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e870: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
e880: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
e890: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
e8a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
e8b0: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
e8c0: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
e8d0: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
e8e0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
e8f0: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
e900: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
e910: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
e920: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
e930: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
e940: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
e950: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
e960: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
e970: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e980: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
e990: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
e9a0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
e9b0: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
e9c0: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
e9d0: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
e9e0: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
e9f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ea00: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
ea10: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
ea20: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ea30: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
ea40: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
ea50: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
ea60: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
ea70: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
ea80: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
ea90: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
eaa0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
eab0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
eac0: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
ead0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
eae0: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
eaf0: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
eb00: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
eb10: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
eb20: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
eb30: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
eb40: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
eb50: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
eb60: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
eb70: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
eb80: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
eb90: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
eba0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
ebb0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ebc0: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
ebd0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ebe0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
ebf0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ec00: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
ec10: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
ec20: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
ec30: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
ec40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
ec50: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
ec60: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
ec70: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
ec80: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
ec90: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
eca0: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
ecb0: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
ecc0: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
ecd0: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
ece0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
ecf0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
ed00: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
ed10: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
ed20: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
ed30: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
ed40: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
ed50: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
ed60: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
ed70: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
ed80: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
ed90: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
eda0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
edb0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
edc0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
edd0: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
ede0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
edf0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
ee00: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
ee10: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
ee20: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
ee30: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
ee40: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
ee50: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
ee60: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
ee70: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
ee80: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
ee90: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
eea0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
eeb0: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
eec0: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
eed0: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
eee0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
eef0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
ef00: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
ef10: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
ef20: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
ef30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
ef40: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
ef50: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
ef60: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
ef70: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
ef80: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
ef90: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
efa0: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
efb0: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
efc0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
efd0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
efe0: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
eff0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
f000: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
f010: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
f020: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
f030: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
f040: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
f050: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
f060: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
f070: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
f080: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
f090: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
f0a0: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
f0b0: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
f0c0: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
f0d0: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
f0e0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
f0f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f100: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
f110: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
f120: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
f130: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
f140: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
f150: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
f160: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
f170: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
f180: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
f190: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
f1a0: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
f1b0: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
f1c0: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
f1d0: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
f1e0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
f1f0: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
f200: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
f210: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
f220: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
f230: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
f240: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
f250: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
f260: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
f270: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
f280: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
f290: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
f2a0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
f2b0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
f2c0: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
f2d0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
f2e0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
f2f0: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
f300: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
f310: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
f320: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
f330: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
f340: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f350: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
f360: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
f370: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
f380: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
f390: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f3a0: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
f3b0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
f3c0: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
f3d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f3e0: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
f3f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
f400: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
f410: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
f420: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
f430: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
f440: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
f450: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
f460: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
f470: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
f480: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
f490: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
f4a0: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
f4b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
f4c0: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
f4d0: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
f4e0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f4f0: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
f500: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
f510: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
f520: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
f530: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
f540: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
f550: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
f560: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f570: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
f580: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
f590: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
f5a0: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
f5b0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
f5c0: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
f5d0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
f5e0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
f5f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
f600: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
f610: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
f620: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
f630: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
f640: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
f650: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
f660: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f670: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
f680: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
f690: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
f6a0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
f6b0: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
f6c0: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
f6d0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
f6e0: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
f6f0: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
f700: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
f710: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
f720: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
f730: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
f740: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
f750: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
f760: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
f770: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
f780: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
f790: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
f7a0: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
f7b0: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
f7c0: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
f7d0: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
f7e0: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
f7f0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
f800: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
f810: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
f820: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
f830: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
f840: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
f850: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
f860: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
f870: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
f880: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
f890: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
f8a0: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
f8b0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f8c0: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
f8d0: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
f8e0: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
f8f0: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
f900: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
f910: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
f920: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
f930: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f940: 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
f950: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
f960: 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
f970: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f980: 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
f990: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
f9a0: 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
f9b0: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
f9c0: 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
f9d0: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
f9e0: 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
f9f0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
fa00: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
fa10: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
fa20: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
fa30: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
fa40: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
fa50: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
fa60: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
fa70: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
fa80: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
fa90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
faa0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
fab0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
fac0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
fad0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
fae0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
faf0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
fb00: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
fb10: 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
fb20: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
fb30: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
fb40: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
fb50: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
fb60: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
fb70: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fb80: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
fb90: 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
fba0: 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
fbb0: 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
fbc0: 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
fbd0: 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
fbe0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
fbf0: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
fc00: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
fc10: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
fc20: 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
fc30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
fc40: 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
fc50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
fc60: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fc70: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
fc80: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
fc90: 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
fca0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
fcb0: 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
fcc0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
fcd0: 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
fce0: 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
fcf0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
fd00: 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
fd10: 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
fd20: 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
fd30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fd40: 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
fd50: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
fd60: 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
fd70: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
fd80: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
fd90: 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
fda0: 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
fdb0: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
fdc0: 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
fdd0: 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
fde0: 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
fdf0: 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
fe00: 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
fe10: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
fe20: 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
fe30: 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
fe40: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
fe50: 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
fe60: 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
fe70: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
fe80: 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
fe90: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
fea0: 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
feb0: 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
fec0: 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
fed0: 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
fee0: 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  cessful..*/.int 
fef0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
ff00: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
ff10: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
ff20: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
ff30: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
ff40: 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
ff50: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
ff60: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
ff70: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
ff80: 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
ff90: 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
ffa0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
ffb0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
ffc0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
ffd0: 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
ffe0: 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
fff0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
10000 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
10010 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
10020 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
10030 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
10040 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10050 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
10060 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10070 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
10080 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
10090 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
100a0 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
100b0 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
100c0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
100d0 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
100e0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
100f0 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
10100 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10110 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
10120 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
10130 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
10140 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
10150 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
10160 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
10170 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
10180 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
10190 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
101a0 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
101b0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
101c0 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
101d0 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
101e0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
101f0 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
10200 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
10210 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
10220 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
10230 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
10240 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
10250 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
10260 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
10270 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
10280 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
10290 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
102a0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
102b0 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
102c0 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
102d0 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
102e0 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
102f0 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
10300 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
10310 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
10320 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
10330 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
10340 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
10350 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
10360 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
10370 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
10380 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
10390 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
103a0 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
103b0 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
103c0 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
103d0 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
103e0 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
103f0 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
10400 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
10410 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
10420 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
10430 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
10440 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
10450 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
10460 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
10470 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
10480 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
10490 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
104a0 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
104b0 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
104c0 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
104d0 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
104e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
104f0 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
10500 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
10510 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
10520 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
10530 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
10540 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
10550 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
10560 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
10570 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
10580 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
10590 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
105a0 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
105b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
105c0 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
105d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
105e0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
105f0 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
10600 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
10610 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
10620 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
10630 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
10640 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
10650 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
10660 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
10670 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
10680 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
10690 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
106a0 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
106b0 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
106c0 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
106d0 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
106e0 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
106f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
10700 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
10710 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
10720 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
10730 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
10740 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
10750 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10760 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
10770 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
10780 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
10790 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
107a0 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tor.  For exampl
107b0 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
107c0 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
107d0 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
107e0 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
107f0 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
10800 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
10810 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
10820 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
10830 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
10840 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10850 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
10860 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
10870 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
10880 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
10890 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
108a0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
108b0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
108c0 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
108d0 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
108e0 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
108f0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
10900 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
10910 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
10920 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
10930 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
10940 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
10950 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
10960 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
10970 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
10980 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
10990 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
109a0 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
109b0 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
109c0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
109d0 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
109e0 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
109f0 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
10a00 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
10a10 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
10a20 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
10a30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
10a40 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
10a50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10a60 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
10a70 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
10a80 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
10a90 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
10aa0 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
10ab0 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
10ac0 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
10ad0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
10ae0 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
10af0 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
10b00 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
10b10 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
10b20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
10b30 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
10b40 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
10b50 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
10b60 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
10b70 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
10b80 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
10b90 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
10ba0 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
10bb0 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
10bc0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
10bd0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
10be0 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
10bf0 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
10c00 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
10c10 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
10c20 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
10c30 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
10c40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
10c50 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
10c60 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
10c70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
10c80 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
10c90 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
10ca0 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
10cb0 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
10cc0 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
10cd0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
10ce0 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
10cf0 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
10d00 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
10d10 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
10d20 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
10d30 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
10d40 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
10d50 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
10d60 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
10d70 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
10d80 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
10d90 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
10da0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
10db0 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
10dc0 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
10dd0 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
10de0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
10df0 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
10e00 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
10e10 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
10e20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
10e30 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
10e40 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
10e50 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10e60 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
10e70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
10e80 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10e90 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
10ea0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
10eb0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
10ec0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
10ed0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
10ee0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
10ef0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
10f00 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
10f10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10f20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
10f30 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
10f40 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
10f50 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
10f60 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
10f70 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
10f80 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
10f90 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
10fa0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
10fb0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
10fc0 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
10fd0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
10fe0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
10ff0 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
11000 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
11010 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
11020 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11030 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
11040 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
11050 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
11060 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
11070 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
11080 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
11090 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
110a0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
110b0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
110c0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
110d0 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
110e0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
110f0 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
11100 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
11110 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
11120 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
11130 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
11140 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
11150 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
11160 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
11170 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
11180 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
11190 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
111a0 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
111b0 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
111c0 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
111d0 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
111e0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
111f0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
11200 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
11210 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
11220 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
11230 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
11240 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
11250 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
11260 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
11270 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
11280 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
11290 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
112a0 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
112b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
112c0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
112d0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
112e0 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
112f0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
11300 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
11310 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
11320 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
11330 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11340 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
11350 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11360 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
11370 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
11380 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
11390 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
113a0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
113b0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
113c0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
113d0 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
113e0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
113f0 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
11400 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
11410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11420 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11430 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
11440 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
11450 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
11460 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
11470 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
11480 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11490 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
114a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
114b0 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
114c0 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
114d0 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
114e0 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
114f0 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
11500 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
11510 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
11520 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
11530 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
11540 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
11550 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11560 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
11570 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
11580 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11590 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
115a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
115b0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
115c0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
115d0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
115e0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
115f0 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
11600 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
11610 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
11620 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
11630 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
11640 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
11650 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
11660 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
11670 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
11680 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
11690 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
116a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
116b0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
116c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
116d0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
116e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
116f0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
11700 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
11710 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
11720 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
11730 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
11740 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
11750 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
11760 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
11770 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
11780 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
11790 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
117a0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
117b0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
117c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
117d0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
117e0 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
117f0 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
11800 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
11810 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11820 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
11830 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
11840 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
11850 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
11860 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
11870 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11880 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
11890 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
118a0 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
118b0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
118c0 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
118d0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
118e0 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
118f0 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
11900 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
11910 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
11920 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
11930 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
11940 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11950 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11960 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11970 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11980 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11990 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
119a0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
119b0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
119c0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
119d0 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
119e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
119f0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
11a00 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
11a10 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
11a20 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
11a30 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
11a40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11a50 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
11a60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11a70 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
11a80 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11a90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11aa0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11ab0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11ac0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11ad0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11ae0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
11af0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
11b00 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
11b10 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
11b20 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
11b30 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
11b40 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
11b50 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
11b60 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
11b70 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
11b80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11b90 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
11ba0 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
11bb0 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
11bc0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
11bd0 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
11be0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
11bf0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
11c00 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
11c10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
11c20 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
11c30 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
11c40 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11c50 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
11c60 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
11c70 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
11c80 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11c90 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11ca0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11cb0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11cc0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
11cd0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
11ce0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
11cf0 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
11d00 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11d10 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
11d20 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
11d30 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
11d40 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
11d50 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11d60 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
11d70 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
11d80 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
11d90 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
11da0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
11db0 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
11dc0 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
11dd0 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
11de0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
11df0 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
11e00 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
11e10 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
11e20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11e30 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
11e40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11e50 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
11e60 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
11e70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
11e80 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
11e90 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
11ea0 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
11eb0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
11ec0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
11ed0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
11ee0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
11ef0 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
11f00 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
11f10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
11f20 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
11f30 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
11f40 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
11f50 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
11f60 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
11f70 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
11f80 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
11f90 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
11fa0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
11fb0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
11fc0 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
11fd0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
11fe0 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
11ff0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12000 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
12010 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
12020 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
12030 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
12040 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
12050 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
12060 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
12070 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
12080 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
12090 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
120a0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
120b0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
120c0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
120d0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
120e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
120f0 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
12100 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12110 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
12120 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12130 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
12140 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
12150 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
12160 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
12170 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
12180 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12190 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
121a0 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
121b0 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
121c0 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
121d0 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
121e0 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
121f0 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
12200 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
12210 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
12220 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
12230 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
12240 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
12250 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
12260 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
12270 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
12280 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68  ple of 16..** Th
12290 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
122a0 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
122b0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
122c0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
122d0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
122e0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
122f0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
12300 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
12310 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68  than two scratch
12320 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
12330 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
12340 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
12350 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65  wice the expecte
12360 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
12370 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20   of threads..** 
12380 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
12390 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72  er require a scr
123a0 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
123b0 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
123c0 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
123d0 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
123e0 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
123f0 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
12400 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
12410 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
12420 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
12430 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
12440 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
12450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
12460 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
12470 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
12480 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
12490 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
124a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
124b0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
124c0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
124d0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
124e0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
124f0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
12500 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
12510 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
12520 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
12530 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
12540 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
12550 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
12560 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
12570 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
12580 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
12590 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
125a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
125b0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
125c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
125d0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
125e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
125f0 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e  _PCACHE2 option.
12600 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
12610 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
12620 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
12630 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
12640 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
12650 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
12660 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
12670 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
12680 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
12690 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
126a0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
126b0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
126c0 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
126d0 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
126e0 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
126f0 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
12700 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
12710 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
12720 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
12730 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
12740 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
12750 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
12760 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
12770 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
12780 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
12790 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
127a0 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
127b0 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
127c0 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
127d0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
127e0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
127f0 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
12800 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
12810 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
12820 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
12830 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
12840 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
12850 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
12860 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
12870 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
12880 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
12890 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
128a0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
128b0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
128c0 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
128d0 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
128e0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
128f0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
12900 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
12910 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
12920 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12930 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
12940 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
12950 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
12960 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
12970 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
12980 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
12990 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
129a0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
129b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
129c0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
129d0 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
129e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
129f0 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
12a00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
12a10 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
12a20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
12a30 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
12a40 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
12a50 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
12a60 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
12a70 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
12a80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
12a90 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
12aa0 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
12ab0 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
12ac0 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
12ad0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12ae0 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
12af0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12b00 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
12b10 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
12b20 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
12b30 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
12b40 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
12b50 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
12b60 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
12b70 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
12b80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
12b90 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
12ba0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
12bb0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
12bc0 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
12bd0 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
12be0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
12bf0 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
12c00 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
12c10 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
12c20 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
12c30 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
12c40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12c50 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
12c60 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
12c70 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
12c80 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
12c90 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
12ca0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
12cb0 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
12cc0 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
12cd0 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
12ce0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
12cf0 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
12d00 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
12d10 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
12d20 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
12d30 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
12d40 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
12d50 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
12d60 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
12d70 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
12d80 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
12d90 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
12da0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
12db0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
12dc0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
12dd0 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
12de0 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
12df0 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
12e00 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
12e10 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
12e20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
12e30 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
12e40 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12e50 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
12e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
12e70 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
12e80 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12e90 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12ea0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12eb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
12ec0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12ed0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
12ee0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12ef0 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
12f00 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
12f10 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
12f20 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
12f30 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
12f40 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
12f50 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
12f60 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
12f70 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
12f80 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
12f90 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  ** content of th
12fa0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
12fb0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12fc0 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
12fd0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
12fe0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
12ff0 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
13000 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13010 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13020 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13030 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13040 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13050 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
13060 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
13070 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
13080 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
13090 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
130a0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
130b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
130c0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
130d0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
130e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
130f0 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13100 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
13110 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13120 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13130 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
13140 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13150 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
13160 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13170 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13180 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
13190 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
131a0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
131b0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
131c0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
131d0 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
131e0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
131f0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
13200 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
13210 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
13220 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
13230 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
13240 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
13250 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
13260 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
13270 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
13280 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
13290 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
132a0 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
132b0 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
132c0 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
132d0 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
132e0 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
132f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13300 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13310 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13320 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13330 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13340 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13350 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
13360 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
13370 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
13380 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
13390 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
133a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
133b0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
133c0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
133d0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
133e0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
133f0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13400 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
13410 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13420 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
13430 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13440 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
13450 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
13460 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
13470 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
13480 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
13490 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
134a0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
134b0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
134c0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
134d0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
134e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
134f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13500 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
13510 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
13520 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
13530 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
13540 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
13550 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
13560 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
13570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
13580 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
13590 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
135a0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
135b0 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
135c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
135d0 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
135e0 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
135f0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
13600 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
13610 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
13620 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13630 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
13640 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
13650 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13660 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13670 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
13680 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
13690 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
136a0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
136b0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
136c0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
136d0 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
136e0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
136f0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
13700 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
13710 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
13720 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
13730 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
13740 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
13750 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
13760 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
13770 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
13780 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
13790 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
137a0 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
137b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
137c0 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
137d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
137e0 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
137f0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
13800 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13810 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13820 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
13830 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
13840 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
13850 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
13860 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
13870 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
13880 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
13890 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
138a0 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
138b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
138c0 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
138d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
138e0 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
138f0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13900 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20  G_LOG option is 
13910 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
13920 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  e the SQLite.** 
13930 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f  global [error lo
13940 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c  g]..** (^The SQL
13950 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
13960 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
13970 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
13980 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
13990 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
139a0 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
139b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
139c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
139d0 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
139e0 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
139f0 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
13a00 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
13a10 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
13a20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
13a30 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
13a40 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
13a50 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
13a60 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
13a70 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
13a80 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
13a90 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
13aa0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
13ab0 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
13ac0 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
13ad0 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
13ae0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
13af0 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
13b00 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
13b10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
13b20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
13b30 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
13b40 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
13b50 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
13b60 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
13b70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13b80 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
13b90 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
13ba0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
13bb0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
13bc0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
13bd0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
13be0 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
13bf0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
13c00 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
13c10 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
13c20 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
13c30 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
13c40 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
13c50 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
13c60 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
13c70 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
13c80 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
13c90 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
13ca0 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
13cb0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
13cc0 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
13cd0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
13ce0 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
13cf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
13d00 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
13d10 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
13d20 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
13d30 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
13d40 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
13d50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
13d60 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
13d70 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
13d80 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
13d90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13da0 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
13db0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
13dc0 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20 6f 70 74  * <dd>^(This opt
13dd0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
13de0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
13df0 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d  ype int. If non-
13e00 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52  zero, then.** UR
13e10 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
13e20 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
13e30 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
13e40 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55   is zero, then U
13e50 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69  RI handling.** i
13e60 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
13e70 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
13e80 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
13e90 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c  lly enabled, all
13ea0 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61   filenames.** pa
13eb0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
13ec0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
13ed0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b  e3_open_v2()], [
13ee0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
13ef0 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65  ] or.** specifie
13f00 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54  d as part of [AT
13f10 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61  TACH] commands a
13f20 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
13f30 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65  s URIs, regardle
13f40 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72  ss.** of whether
13f50 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c   or not the [SQL
13f60 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
13f70 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
13f80 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
13f90 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
13fa0 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67  ned. ^If it is g
13fb0 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
13fc0 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
13fd0 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
13fe0 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
13ff0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
14000 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
14010 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
14020 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
14030 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64  s opened. ^(By d
14040 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
14050 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
14060 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
14070 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
14080 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
14090 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
140a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
140b0 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
140c0 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  defined.)^.**.**
140d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
140e0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
140f0 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SCAN]] <dt>SQLIT
14100 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
14110 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20  G_INDEX_SCAN.** 
14120 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e  <dd>^This option
14130 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14140 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74  integer argument
14150 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
14160 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f  reted as.** a bo
14170 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
14180 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
14190 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
141a0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
141b0 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c  for.** full tabl
141c0 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
141d0 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20  uery optimizer. 
141e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
141f0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
14200 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
14210 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
14220 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
14230 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14240 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
14250 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
14260 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14270 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
14280 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
14290 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
142a0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
142b0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
142c0 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
142d0 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
142e0 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
142f0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
14300 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
14310 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
14320 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
14330 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
14340 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
14350 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
14360 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
14370 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
14380 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
14390 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
143a0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
143b0 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
143c0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
143d0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
143e0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
143f0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
14400 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
14410 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
14420 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
14430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14440 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
14450 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
14460 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
14470 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
14480 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
14490 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
144a0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
144b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
144c0 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
144d0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
144e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
144f0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
14500 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14510 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
14520 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
14530 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
14540 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
14550 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
14560 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
14570 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
14580 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
14590 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
145a0 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
145b0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
145c0 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
145d0 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
145e0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
145f0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
14600 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
14610 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
14620 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
14630 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
14640 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
14650 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
14660 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
14670 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
14680 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
14690 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
146a0 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
146b0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
146c0 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
146d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
146e0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
146f0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
14700 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
14710 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
14720 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
14730 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
14740 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
14750 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
14760 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
14770 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
14780 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
14790 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
147a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
147b0 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
147c0 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
147d0 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
147e0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
147f0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
14800 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
14810 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
14820 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
14830 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
14840 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
14850 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
14860 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
14870 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
14880 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
14890 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
148a0 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
148b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
148c0 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
148d0 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
148e0 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
148f0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
14900 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
14910 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
14920 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14930 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
14940 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14950 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
14960 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
14970 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
14980 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
14990 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
149a0 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
149b0 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
149c0 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
149d0 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
149e0 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
149f0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
14a00 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
14a10 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
14a20 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
14a30 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
14a40 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
14a50 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
14a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14a70 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
14a80 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
14a90 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
14aa0 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
14ab0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
14ac0 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
14ad0 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
14ae0 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
14af0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
14b00 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  * cannot be chan
14b10 67 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e  ged at run-time.
14b20 20 20 4e 6f 72 20 6d 61 79 20 74 68 65 20 6d 61    Nor may the ma
14b30 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
14b40 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78 63 65 65  ap size.** excee
14b50 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  d the compile-ti
14b60 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
14b70 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
14b80 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
14b90 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
14ba0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
14bb0 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
14bc0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
14bd0 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
14be0 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
14bf0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
14c00 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
14c10 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
14c20 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
14c30 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
14c40 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
14c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
14c60 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
14c70 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e  <dd>^This option
14c80 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
14c90 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
14ca0 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e  compiled for Win
14cb0 64 6f 77 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  dows.** with the
14cc0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
14cd0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
14ce0 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
14cf0 65 64 2e 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  ed..** SQLITE_CO
14d00 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
14d10 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
14d20 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
14d30 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
14d40 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
14d50 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
14d60 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
14d70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
14d80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14d90 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
14da0 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
14db0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14dc0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
14dd0 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
14de0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14df0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
14e00 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
14e10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14e20 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
14e30 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
14e40 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
14e50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14e60 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
14e70 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
14e80 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
14e90 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14ea0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
14eb0 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
14ec0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
14ed0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
14ee0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
14ef0 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
14f00 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
14f10 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
14f20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14f30 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
14f40 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
14f50 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
14f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14f70 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
14f80 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
14f90 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
14fa0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14fb0 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
14fc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14fd0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
14fe0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14ff0 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
15000 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
15010 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
15020 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
15030 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
15040 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
15050 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
15060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15070 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
15080 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
15090 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
150a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
150b0 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e  E       14  /* n
150c0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
150d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
150e0 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
150f0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
15100 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15110 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
15120 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
15130 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15140 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20  ITE_CONFIG_URI  
15150 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69          17  /* i
15160 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
15170 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15180 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20  HE2      18  /* 
15190 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
151a0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
151b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
151c0 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31  G_GETPCACHE2   1
151d0 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  9  /* sqlite3_pc
151e0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
151f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15200 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
15210 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20  _INDEX_SCAN 20  
15220 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
15230 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15240 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20  SQLLOG       21 
15250 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69   /* xSqllog, voi
15260 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
15270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15280 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20  _SIZE    22  /* 
15290 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73  sqlite3_int64, s
152a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a  qlite3_int64 */.
152b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
152c0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
152d0 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a  SIZE      23  /*
152e0 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f   int nByte */../
152f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
15300 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
15310 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
15320 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
15330 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
15340 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
15350 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
15360 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
15370 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
15380 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
15390 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
153a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
153b0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
153c0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
153d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
153e0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
153f0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
15400 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
15410 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
15420 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
15430 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
15440 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
15450 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
15460 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
15470 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
15480 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
15490 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
154a0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
154b0 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
154c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
154d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
154e0 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
154f0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
15500 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
15510 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
15520 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
15530 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
15540 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
15550 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
15560 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15570 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
15580 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
15590 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
155a0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
155b0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
155c0 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
155d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
155e0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
155f0 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
15600 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
15610 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
15620 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
15630 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
15640 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15650 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
15660 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
15670 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
15680 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
15690 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
156a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
156b0 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
156c0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
156d0 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
156e0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
156f0 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
15700 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
15710 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
15720 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
15730 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
15740 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
15750 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
15760 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
15770 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
15780 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
15790 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
157a0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
157b0 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
157c0 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
157d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
157e0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
157f0 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
15800 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
15810 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
15820 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
15830 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
15840 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
15850 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
15860 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
15870 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15880 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
15890 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
158a0 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
158b0 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
158c0 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
158d0 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
158e0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
158f0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
15900 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
15910 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
15920 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
15930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15940 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
15950 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
15960 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
15970 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
15980 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
15990 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
159a0 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
159b0 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
159c0 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
159d0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
159e0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
159f0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15a00 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
15a10 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
15a20 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
15a30 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15a40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
15a50 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
15a60 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
15a70 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
15a80 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
15a90 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
15aa0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
15ab0 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
15ac0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
15ad0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
15ae0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15af0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
15b00 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
15b10 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
15b20 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
15b30 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
15b40 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
15b50 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
15b60 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
15b70 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
15b80 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
15b90 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
15ba0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
15bb0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
15bc0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
15bd0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
15be0 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
15bf0 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
15c00 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
15c10 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
15c20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
15c30 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15c40 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
15c50 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
15c60 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
15c70 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
15c80 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
15c90 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
15ca0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
15cb0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
15cc0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
15cd0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
15ce0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
15cf0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
15d00 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
15d10 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
15d20 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
15d30 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
15d40 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
15d50 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
15d60 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
15d70 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
15d80 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
15d90 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
15da0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
15db0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
15dc0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
15dd0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15de0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
15df0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
15e00 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
15e10 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
15e20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
15e30 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
15e40 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
15e50 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
15e60 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
15e70 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
15e80 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
15e90 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
15ea0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
15eb0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
15ec0 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
15ed0 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
15ee0 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
15ef0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
15f00 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15f10 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
15f20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
15f30 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
15f40 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
15f50 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
15f60 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
15f70 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
15f80 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
15f90 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
15fa0 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
15fb0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
15fc0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
15fd0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
15fe0 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20     1002  /* int 
15ff0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
16000 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16010 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
16020 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1003  /* int int
16030 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  * */.../*.** CAP
16040 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
16050 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
16060 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
16070 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
16080 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
16090 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
160a0 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
160b0 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
160c0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
160d0 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
160e0 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
160f0 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
16100 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
16110 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
16120 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
16130 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69  patibility..*/.i
16140 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
16150 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
16160 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
16170 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
16180 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
16190 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
161a0 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
161b0 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
161c0 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
161d0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
161e0 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
161f0 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
16200 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
16210 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
16220 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
16230 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
16240 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
16250 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
16260 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
16270 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
16280 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
16290 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
162a0 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
162b0 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
162c0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
162d0 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
162e0 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
162f0 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
16300 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
16310 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
16320 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
16330 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
16340 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
16350 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
16360 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
16370 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
16380 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
16390 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74   .** most recent
163a0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
163b0 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
163c0 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
163d0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
163e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
163f0 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65  tion D..** ^Inse
16400 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55  rts into [WITHOU
16410 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20  T ROWID] tables 
16420 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64  are not recorded
16430 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
16440 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
16450 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
16460 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  es.** have ever 
16470 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20  occurred on the 
16480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16490 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20  ion D, .** then 
164a0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
164b0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74  ert_rowid(D) ret
164c0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
164d0 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
164e0 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
164f0 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74  a trigger or wit
16500 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74  hin a [virtual t
16510 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c  able].** method,
16520 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
16530 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ne will return t
16540 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
16550 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
16560 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  w as long as the
16570 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
16580 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
16590 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
165a0 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
165b0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
165c0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64  table method end
165d0 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
165e0 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
165f0 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
16600 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
16610 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
16620 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a  ger or virtual.*
16630 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62  * table method b
16640 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  egan.)^.**.** ^A
16650 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
16660 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
16670 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
16680 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
16690 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
166a0 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
166b0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
166c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
166d0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
166e0 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
166f0 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
16700 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
16710 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
16720 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
16730 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
16740 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
16750 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
16760 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
16770 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
16780 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
16790 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
167a0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
167b0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
167c0 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
167d0 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
167e0 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
167f0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
16800 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
16810 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
16820 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
16830 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
16840 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
16850 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
16860 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
16870 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
16880 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
16890 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
168a0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
168b0 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
168c0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
168d0 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
168e0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
168f0 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
16900 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
16910 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
16920 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
16930 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
16940 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
16950 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
16960 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
16970 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
16980 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
16990 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
169a0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
169b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
169c0 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
169d0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
169e0 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
169f0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
16a00 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
16a10 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
16a20 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
16a30 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
16a40 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
16a50 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16a60 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
16a70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
16a80 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
16a90 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
16aa0 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
16ab0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
16ac0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
16ad0 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
16ae0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
16af0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
16b00 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
16b10 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
16b20 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
16b30 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
16b40 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
16b50 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
16b60 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
16b70 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72  nged.** or inser
16b80 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62  ted or deleted b
16b90 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
16ba0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51  tly completed SQ
16bb0 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f  L statement.** o
16bc0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
16bd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
16be0 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
16bf0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
16c00 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20   ^(Only changes 
16c10 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
16c20 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
16c30 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  he [INSERT], [UP
16c40 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45  DATE],.** or [DE
16c50 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20  LETE] statement 
16c60 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
16c70 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
16c80 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
16c90 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67  ggers or [foreig
16ca0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
16cb0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29  re not counted.)
16cc0 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  ^ Use the.** [sq
16cd0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
16ce0 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ges()] function 
16cf0 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
16d00 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
16d10 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67  ges.** including
16d20 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
16d30 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20  by triggers and 
16d40 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
16d50 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e  ons..**.** ^Chan
16d60 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
16d70 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64  at are simulated
16d80 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20   by an [INSTEAD 
16d90 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61  OF trigger].** a
16da0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
16db0 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65   Only real table
16dc0 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
16dd0 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20  nted..**.** ^(A 
16de0 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20  "row change" is 
16df0 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69  a change to a si
16e00 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69  ngle row of a si
16e10 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61  ngle table.** ca
16e20 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52  used by an INSER
16e30 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50  T, DELETE, or UP
16e40 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20  DATE statement. 
16e50 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72   Rows that.** ar
16e60 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64  e changed as sid
16e70 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45  e effects of [RE
16e80 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
16e90 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
16ea0 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
16eb0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52   processing, [DR
16ec0 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79  OP TABLE], or by
16ed0 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
16ee0 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
16ef0 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
16f00 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a  row changes.)^.*
16f10 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
16f20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
16f30 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
16f40 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
16f50 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
16f60 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43  e script of a [C
16f70 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
16f80 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f  trigger]. .** Mo
16f90 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
16fa0 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
16fb0 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
16fc0 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
16fd0 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
16fe0 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
16ff0 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
17000 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
17010 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
17020 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
17030 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
17040 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
17050 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
17060 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
17070 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
17080 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
17090 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
170a0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
170b0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
170c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
170d0 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
170e0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
170f0 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
17100 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
17110 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
17120 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
17130 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
17140 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
17150 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
17160 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
17170 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
17180 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
17190 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
171a0 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
171b0 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  us, when called 
171c0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
171d0 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
171e0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
171f0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
17200 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
17210 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
17220 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
17230 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
17240 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
17250 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69   level.  ^(Withi
17260 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
17270 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
17280 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
17290 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
172a0 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
172b0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
172c0 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
172d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
172e0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
172f0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
17300 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
17310 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
17320 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
17330 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
17340 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
17350 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
17360 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
17370 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
17380 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
17390 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
173a0 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a  wn context.)^.**
173b0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
173c0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
173d0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
173e0 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
173f0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
17400 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
17410 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
17420 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
17430 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
17440 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
17450 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
17460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
17470 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
17480 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
17490 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
174a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
174b0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
174c0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
174d0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
174e0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
174f0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
17500 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
17510 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
17520 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
17530 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
17540 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
17550 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
17560 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52  caused by [INSER
17570 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20  T],.** [UPDATE] 
17580 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
17590 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
175a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
175b0 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
175c0 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e  d..** ^(The coun
175d0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  t returned by sq
175e0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
175f0 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61  ges() includes a
17600 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72  ll changes.** fr
17610 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54  om all [CREATE T
17620 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
17630 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63  ] contexts and c
17640 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a  hanges made by.*
17650 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
17660 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72  ctions]. However
17670 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64  ,.** the count d
17680 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
17690 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20  changes used to 
176a0 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41  implement [REPLA
176b0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  CE] constraints,
176c0 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  .** do rollbacks
176d0 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
176e0 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54  sing, or [DROP T
176f0 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67  ABLE] processing
17700 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20  .  The.** count 
17710 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17720 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74   rows of views t
17730 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53  hat fire an [INS
17740 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
17750 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74  ,.** though if t
17760 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  he INSTEAD OF tr
17770 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e  igger makes chan
17780 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20  ges of its own, 
17790 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a  those changes .*
177a0 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e  * are counted.)^
177b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
177c0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
177d0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73   function counts
177e0 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20   the changes as 
177f0 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73  soon as.** the s
17800 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
17810 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70  kes them is comp
17820 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
17830 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
17840 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f  .** is passed to
17850 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
17860 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
17870 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
17880 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
17890 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
178a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
178b0 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
178c0 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
178d0 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
178e0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
178f0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
17900 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
17910 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
17920 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
17930 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
17940 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
17950 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
17960 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
17970 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
17980 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
17990 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
179a0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
179b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
179c0 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
179d0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
179e0 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
179f0 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
17a00 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
17a10 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
17a20 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
17a30 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
17a40 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
17a50 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
17a60 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
17a70 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
17a80 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
17a90 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
17aa0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
17ab0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
17ac0 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
17ad0 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
17ae0 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
17af0 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
17b00 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
17b10 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
17b20 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
17b30 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
17b40 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
17b50 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
17b60 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
17b70 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
17b80 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
17b90 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
17ba0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
17bb0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
17bc0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
17bd0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
17be0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
17bf0 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
17c00 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
17c10 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
17c20 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
17c30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
17c40 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
17c50 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
17c60 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
17c70 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
17c80 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
17c90 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
17ca0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
17cb0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
17cc0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
17cd0 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
17ce0 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
17cf0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
17d00 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
17d10 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
17d20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
17d30 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
17d40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
17d50 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
17d60 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
17d70 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
17d80 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
17d90 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
17da0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
17db0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
17dc0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
17dd0 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
17de0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
17df0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
17e00 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17e10 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
17e20 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
17e30 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
17e40 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
17e50 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
17e60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
17e70 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
17e80 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
17e90 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
17ea0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
17eb0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17ec0 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
17ed0 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
17ee0 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
17ef0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
17f00 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
17f10 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
17f20 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
17f30 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
17f40 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
17f50 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
17f60 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
17f70 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
17f80 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
17f90 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
17fa0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
17fb0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
17fc0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
17fd0 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
17fe0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
17ff0 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
18000 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
18010 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
18020 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
18030 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
18040 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
18050 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
18060 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
18070 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
18080 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18090 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
180a0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
180b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
180c0 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
180d0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
180e0 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
180f0 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
18100 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
18110 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
18120 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18130 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
18140 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
18150 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
18160 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
18170 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
18180 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
18190 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
181a0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
181b0 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
181c0 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
181d0 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
181e0 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
181f0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
18200 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
18210 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
18220 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
18230 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
18240 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
18250 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
18260 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
18270 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
18280 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
18290 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
182a0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
182b0 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
182c0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
182d0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
182e0 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
182f0 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
18300 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
18310 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
18320 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
18330 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
18340 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
18350 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
18360 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
18370 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
18380 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
18390 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
183a0 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
183b0 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
183c0 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
183d0 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
183e0 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
183f0 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
18400 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
18410 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
18420 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
18430 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
18440 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
18450 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
18460 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
18470 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
18480 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
18490 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
184a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
184b0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
184c0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
184d0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
184e0 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
184f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
18500 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
18510 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
18520 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
18530 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
18540 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
18550 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
18560 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
18570 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
18580 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
18590 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
185a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
185b0 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
185c0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
185d0 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
185e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
185f0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
18600 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
18610 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
18620 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
18630 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
18640 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
18650 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
18660 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
18670 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
18680 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
18690 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
186a0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
186b0 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
186c0 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
186d0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
186e0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
186f0 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
18700 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
18710 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
18720 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
18730 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18740 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
18750 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
18760 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
18770 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
18780 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
18790 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
187a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
187b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
187c0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
187d0 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
187e0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
187f0 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
18800 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
18810 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
18820 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
18830 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
18840 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
18850 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
18860 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
18870 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
18880 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
18890 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
188a0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
188b0 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
188c0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ked..**.** ^If t
188d0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
188e0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
188f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
18900 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
18910 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
18920 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
18930 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
18940 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
18950 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
18960 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
18970 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
18980 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
18990 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
189a0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
189b0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
189c0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
189d0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
189e0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
189f0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
18a00 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
18a10 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
18a20 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
18a30 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
18a40 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
18a50 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
18a60 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
18a70 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
18a80 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
18a90 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
18aa0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
18ab0 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
18ac0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
18ad0 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
18ae0 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
18af0 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
18b00 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
18b10 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
18b20 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
18b30 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
18b40 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
18b50 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
18b60 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
18b70 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
18b80 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
18b90 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
18ba0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
18bb0 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
18bc0 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
18bd0 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
18be0 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
18bf0 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
18c00 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
18c10 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
18c20 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
18c30 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
18c40 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
18c50 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
18c60 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
18c70 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
18c80 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
18c90 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
18ca0 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
18cb0 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
18cc0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
18cd0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
18ce0 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
18cf0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
18d00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
18d10 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
18d20 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
18d30 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
18d40 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
18d50 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
18d60 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
18d70 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
18d80 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
18d90 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
18da0 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
18db0 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
18dc0 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
18dd0 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
18de0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
18df0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
18e00 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
18e10 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
18e20 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
18e30 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
18e40 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
18e50 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
18e60 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
18e70 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
18e80 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
18e90 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
18ea0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
18eb0 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
18ec0 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
18ed0 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
18ee0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
18ef0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
18f00 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
18f10 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
18f20 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
18f30 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
18f40 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
18f50 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
18f60 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
18f70 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
18f80 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
18f90 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
18fa0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
18fb0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
18fc0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
18fd0 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
18fe0 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
18ff0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
19000 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
19010 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
19020 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
19030 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
19040 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
19050 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
19060 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
19070 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
19080 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
19090 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
190a0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
190b0 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
190c0 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
190d0 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
190e0 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
190f0 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
19100 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
19110 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
19120 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
19130 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
19140 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69   readers.  ^If i
19150 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
19160 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
19170 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
19180 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
19190 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
191a0 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
191b0 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
191c0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
191d0 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
191e0 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
191f0 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
19200 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
19210 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
19220 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
19230 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65  ^This error code
19240 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
19250 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
19260 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
19270 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
19280 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
19290 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
192a0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
192b0 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
192c0 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
192d0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
192e0 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
192f0 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
19300 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
19310 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
19320 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
19330 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
19340 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
19350 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
19360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19370 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
19380 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
19390 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
193a0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
193b0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
193c0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
193d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
193e0 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
193f0 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
19400 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19410 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
19420 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
19430 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
19440 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
19450 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
19460 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
19470 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
19480 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
19490 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
194a0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
194b0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
194c0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
194d0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
194e0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
194f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
19500 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
19510 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
19520 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
19530 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
19540 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19550 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
19560 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
19570 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
19580 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
19590 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a  Busy Timeout.**.
195a0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
195b0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
195c0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
195d0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
195e0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
195f0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
19600 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
19610 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
19620 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
19630 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
19640 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
19650 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
19660 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
19670 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
19680 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
19690 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
196a0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
196b0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
196c0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
196d0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
196e0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
196f0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
19700 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
19710 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
19720 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
19730 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
19740 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
19750 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
19760 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
19770 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
19780 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
19790 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
197a0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
197b0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
197c0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
197d0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
197e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
197f0 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
19800 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
19810 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
19820 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
19830 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
19840 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
19850 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
19860 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
19870 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
19880 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
19890 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73  ared.)^.*/.int s
198a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
198b0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
198c0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
198d0 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
198e0 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
198f0 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
19900 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
19910 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
19920 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
19930 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
19940 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
19950 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
19960 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
19970 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
19980 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
19990 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
199a0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
199b0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
199c0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
199d0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
199e0 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
199f0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
19a00 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
19a10 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
19a20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
19a30 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
19a40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
19a50 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
19a60 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
19a70 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
19a80 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
19a90 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
19aa0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
19ab0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
19ac0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
19ad0 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
19ae0 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
19af0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
19b00 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
19b10 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
19b20 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
19b30 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
19b40 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
19b50 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
19b60 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
19b70 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
19b80 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
19b90 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
19ba0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
19bb0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
19bc0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
19bd0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
19be0 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
19bf0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
19c00 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
19c10 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
19c20 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
19c30 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
19c40 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
19c50 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
19c60 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
19c70 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
19c80 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
19c90 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
19ca0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
19cb0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
19cc0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
19cd0 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
19ce0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
19cf0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
19d00 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
19d10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
19d20 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
19d30 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
19d40 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
19d50 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
19d60 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
19d70 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
19d80 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
19d90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
19da0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
19db0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
19dc0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
19dd0 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
19de0 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
19df0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
19e00 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
19e10 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19e20 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
19e30 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
19e40 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
19e50 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
19e60 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
19e70 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
19e80 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
19e90 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
19ea0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
19eb0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
19ec0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
19ed0 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
19ee0 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
19ef0 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
19f00 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
19f10 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
19f20 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
19f30 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
19f40 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
19f50 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
19f60 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
19f70 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
19f80 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
19f90 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
19fa0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
19fb0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
19fc0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
19fd0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19fe0 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
19ff0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a000 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1a010 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1a020 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1a030 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1a040 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1a050 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1a060 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a070 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1a080 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a090 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1a0a0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a0b0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1a0c0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1a0d0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1a0e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1a0f0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1a100 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1a110 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1a120 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1a130 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1a140 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1a150 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1a160 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1a170 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1a180 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1a190 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1a1a0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1a1b0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1a1c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1a1d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1a1e0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1a1f0 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1a200 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1a210 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1a220 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1a230 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1a240 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1a250 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1a260 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1a270 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1a280 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1a290 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1a2a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1a2b0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1a2c0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1a2d0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1a2e0 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1a2f0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1a300 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1a310 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1a320 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1a330 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1a340 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1a350 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1a360 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1a370 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1a380 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1a390 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1a3a0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1a3b0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1a3c0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1a3d0 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1a3e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a3f0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1a400 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1a410 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1a420 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1a430 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1a440 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1a450 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1a460 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1a470 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1a480 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1a490 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
1a4a0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
1a4b0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
1a4c0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
1a4d0 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
1a4e0 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
1a4f0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
1a500 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1a510 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
1a520 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1a530 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
1a540 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a550 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1a560 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1a570 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1a580 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1a590 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1a5a0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1a5b0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1a5c0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1a5d0 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1a5e0 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1a5f0 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1a600 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1a610 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1a620 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1a630 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1a640 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1a650 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1a660 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1a670 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1a680 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1a690 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1a6a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1a6b0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1a6c0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1a6d0 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1a6e0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1a6f0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1a700 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1a710 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1a720 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1a730 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1a740 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1a750 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1a760 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1a770 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1a780 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1a790 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1a7a0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1a7b0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1a7c0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1a7d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1a7e0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1a7f0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1a800 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1a810 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1a820 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1a830 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1a840 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1a850 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1a860 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1a870 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1a880 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1a890 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1a8a0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1a8b0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1a8c0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1a8d0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1a8e0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1a8f0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1a900 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1a910 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1a920 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1a930 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1a940 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1a950 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1a960 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1a970 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1a980 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1a990 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1a9a0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1a9b0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1a9c0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1a9d0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1a9e0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1a9f0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1aa00 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1aa10 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1aa20 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1aa30 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1aa40 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1aa50 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1aa60 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1aa70 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1aa80 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1aa90 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1aaa0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1aab0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1aac0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1aad0 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1aae0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1aaf0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1ab00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1ab10 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1ab20 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1ab30 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1ab40 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1ab50 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1ab60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1ab70 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1ab80 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1ab90 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1aba0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1abb0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1abc0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1abd0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1abe0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1abf0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1ac00 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1ac10 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1ac20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1ac30 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1ac40 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1ac50 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1ac60 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1ac70 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1ac80 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1ac90 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1aca0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1acb0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1acc0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1acd0 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1ace0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1acf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1ad00 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1ad10 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1ad20 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1ad30 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1ad40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1ad50 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1ad60 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1ad70 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1ad80 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1ad90 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1ada0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1adb0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1adc0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1add0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1ade0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1adf0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1ae00 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1ae10 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1ae20 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1ae30 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1ae40 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1ae50 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1ae60 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1ae70 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1ae80 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1ae90 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1aea0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1aeb0 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1aec0 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1aed0 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1aee0 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1aef0 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1af00 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1af10 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1af20 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1af30 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1af40 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1af50 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1af60 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1af70 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1af80 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1af90 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1afa0 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1afb0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1afc0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1afd0 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1afe0 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1aff0 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1b000 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b010 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1b020 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1b030 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1b040 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1b050 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b060 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1b070 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1b080 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1b090 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1b0a0 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1b0b0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1b0c0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1b0d0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1b0e0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1b0f0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b100 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1b110 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1b120 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1b130 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1b140 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1b150 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1b160 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1b170 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1b180 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b190 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1b1a0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1b1b0 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1b1c0 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1b1d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b1e0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1b1f0 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1b200 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1b210 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1b220 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1b230 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1b240 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1b250 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b260 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1b270 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1b280 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1b290 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1b2a0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1b2b0 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1b2c0 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1b2d0 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1b2e0 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1b2f0 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1b300 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1b310 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1b320 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1b330 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1b340 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1b350 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1b360 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1b370 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1b380 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1b390 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1b3a0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1b3b0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1b3c0 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1b3d0 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1b3e0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1b3f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1b400 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1b410 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1b420 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1b430 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1b440 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1b450 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1b460 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b470 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1b480 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1b490 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1b4a0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1b4b0 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1b4c0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1b4d0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1b4e0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1b4f0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1b500 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b510 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1b520 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1b530 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1b540 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1b550 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1b560 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1b570 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1b580 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1b590 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1b5a0 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1b5b0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1b5c0 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1b5d0 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1b5e0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1b5f0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1b600 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1b610 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1b620 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b630 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1b640 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1b650 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1b660 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1b670 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1b680 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1b690 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1b6a0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1b6b0 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1b6c0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1b6d0 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1b6e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1b6f0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1b700 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1b710 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1b720 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1b730 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1b740 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1b750 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1b760 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1b770 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1b780 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1b790 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1b7a0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1b7b0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1b7c0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1b7d0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1b7e0 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1b7f0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1b800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1b810 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1b820 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1b830 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1b840 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1b850 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1b860 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1b870 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1b880 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1b890 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1b8a0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1b8b0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1b8c0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1b8d0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1b8e0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1b8f0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1b900 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1b910 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1b920 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1b930 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1b940 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1b950 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1b960 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1b970 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1b980 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1b990 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1b9a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1b9b0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1b9c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1b9d0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1b9e0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1b9f0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1ba00 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1ba10 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1ba20 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1ba30 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1ba40 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1ba50 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1ba60 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1ba70 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1ba80 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1ba90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1baa0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1bab0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1bac0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1bad0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1bae0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1baf0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1bb00 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1bb10 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1bb20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1bb30 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1bb40 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1bb50 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1bb60 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1bb70 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1bb80 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1bb90 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1bba0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1bbb0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1bbc0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1bbd0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1bbe0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1bbf0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1bc00 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1bc10 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1bc20 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1bc30 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1bc40 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1bc50 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
1bc60 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
1bc70 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1bc80 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1bc90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1bca0 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
1bcb0 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
1bcc0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
1bcd0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1bce0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
1bcf0 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
1bd00 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
1bd10 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
1bd20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
1bd30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1bd40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1bd50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1bd60 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1bd70 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1bd80 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1bd90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1bda0 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
1bdb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1bdc0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1bdd0 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
1bde0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1bdf0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1be00 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
1be10 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1be20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1be30 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1be40 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1be50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1be60 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
1be70 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1be80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1be90 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
1bea0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1beb0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1bec0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1bed0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1bee0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1bef0 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1bf00 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
1bf10 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
1bf20 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1bf30 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1bf40 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1bf50 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1bf60 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1bf70 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1bf80 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1bf90 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1bfa0 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1bfb0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1bfc0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
1bfd0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1bfe0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1bff0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1c000 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
1c010 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
1c020 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
1c030 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1c040 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1c050 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1c060 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
1c070 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1c080 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
1c090 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1c0a0 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1c0b0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1c0c0 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1c0d0 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1c0e0 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1c0f0 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1c100 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1c110 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1c120 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1c130 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1c140 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1c150 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1c160 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1c170 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1c180 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1c190 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1c1a0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1c1b0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1c1c0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1c1d0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1c1e0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1c1f0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1c200 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1c210 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1c220 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1c230 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1c240 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1c250 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1c260 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1c270 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1c280 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1c290 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1c2a0 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1c2b0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1c2c0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1c2d0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1c2e0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1c2f0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1c300 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1c310 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1c320 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1c330 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1c340 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1c350 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
1c360 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1c370 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
1c380 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
1c390 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
1c3a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
1c3b0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
1c3c0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
1c3d0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
1c3e0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
1c3f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
1c400 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1c410 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
1c420 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
1c430 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
1c440 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1c450 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
1c460 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1c470 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
1c480 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
1c490 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
1c4a0 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
1c4b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
1c4c0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
1c4d0 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
1c4e0 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
1c4f0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
1c500 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
1c510 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
1c520 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
1c530 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
1c540 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
1c550 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1c560 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
1c570 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1c580 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
1c590 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1c5a0 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1c5b0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1c5c0 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1c5d0 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1c5e0 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1c5f0 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1c600 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1c610 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1c620 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1c630 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1c640 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1c650 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1c660 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1c670 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1c680 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1c690 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1c6a0 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1c6b0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1c6c0 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1c6d0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1c6e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1c6f0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1c700 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1c710 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1c720 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1c730 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1c740 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1c750 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1c760 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1c770 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1c780 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1c790 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1c7a0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1c7b0 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1c7c0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1c7d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1c7e0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1c7f0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1c800 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1c810 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1c820 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1c830 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1c840 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1c850 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1c860 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1c870 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1c880 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1c890 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1c8a0 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1c8b0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1c8c0 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1c8d0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1c8e0 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1c8f0 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1c900 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1c910 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1c920 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1c930 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1c940 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1c950 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1c960 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1c970 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1c980 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1c990 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1c9a0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1c9b0 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1c9c0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1c9d0 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1c9e0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1c9f0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1ca00 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
1ca10 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1ca20 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1ca30 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1ca40 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1ca50 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1ca60 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1ca70 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1ca80 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1ca90 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1caa0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1cab0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1cac0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1cad0 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1cae0 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1caf0 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1cb00 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1cb10 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1cb20 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1cb30 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1cb40 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1cb50 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1cb60 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1cb70 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1cb80 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1cb90 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1cba0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1cbb0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1cbc0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1cbd0 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1cbe0 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1cbf0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1cc00 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1cc10 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1cc20 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1cc30 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
1cc40 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
1cc50 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
1cc60 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
1cc70 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
1cc80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
1cc90 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
1cca0 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1ccb0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
1ccc0 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
1ccd0 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
1cce0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1ccf0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1cd00 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
1cd10 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
1cd20 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
1cd30 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1cd40 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1cd50 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1cd60 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1cd70 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1cd80 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1cd90 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
1cda0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1cdb0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1cdc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cdd0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1cde0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1cdf0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1ce00 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1ce10 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1ce20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1ce30 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1ce40 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1ce50 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1ce60 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1ce70 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1ce80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ce90 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1cea0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1ceb0 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1cec0 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1ced0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1cee0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1cef0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cf00 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1cf10 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1cf20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1cf30 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1cf40 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1cf50 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1cf60 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1cf70 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1cf80 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1cf90 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1cfa0 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1cfb0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1cfc0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1cfd0 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1cfe0 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1cff0 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1d000 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d010 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1d020 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1d030 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1d040 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1d050 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1d060 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1d070 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1d080 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1d090 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1d0a0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1d0b0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1d0c0 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1d0d0 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1d0e0 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1d0f0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1d100 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1d110 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d120 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1d130 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1d140 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1d150 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1d160 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1d170 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1d180 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d190 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1d1a0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1d1b0 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1d1c0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1d1d0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1d1e0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1d1f0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1d200 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1d210 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1d220 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1d230 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1d240 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1d250 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d260 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1d270 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1d280 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1d290 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1d2a0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1d2b0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1d2c0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1d2d0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1d2e0 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1d2f0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1d300 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1d310 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1d320 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1d330 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1d340 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1d350 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1d360 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1d370 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1d380 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1d390 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1d3a0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1d3b0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1d3c0 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1d3d0 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1d3e0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1d3f0 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1d400 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1d410 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1d420 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1d430 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1d440 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1d450 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1d460 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1d470 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1d480 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1d490 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1d4a0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1d4b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1d4c0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1d4d0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
1d4e0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
1d4f0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1d500 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1d510 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1d520 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
1d530 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
1d540 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
1d550 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
1d560 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
1d570 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1d580 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
1d590 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
1d5a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
1d5b0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
1d5c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
1d5d0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
1d5e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
1d5f0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
1d600 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
1d610 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
1d620 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
1d630 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1d640 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1d650 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
1d660 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d670 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
1d680 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
1d690 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
1d6a0 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
1d6b0 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
1d6c0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
1d6d0 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
1d6e0 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
1d6f0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
1d700 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
1d710 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
1d720 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1d730 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
1d740 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1d750 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
1d760 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
1d770 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
1d780 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1d790 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
1d7a0 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
1d7b0 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
1d7c0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
1d7d0 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
1d7e0 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
1d7f0 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
1d800 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
1d810 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
1d820 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
1d830 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
1d840 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
1d850 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
1d860 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
1d870 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
1d880 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
1d890 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
1d8a0 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
1d8b0 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
1d8c0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
1d8d0 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
1d8e0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
1d8f0 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
1d900 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
1d910 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
1d920 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
1d930 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
1d940 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
1d950 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1d960 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
1d970 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
1d980 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
1d990 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1d9a0 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
1d9b0 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
1d9c0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
1d9d0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
1d9e0 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
1d9f0 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
1da00 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
1da10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1da20 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
1da30 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
1da40 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
1da50 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1da60 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
1da70 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
1da80 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
1da90 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
1daa0 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
1dab0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
1dac0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
1dad0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
1dae0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
1daf0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
1db00 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
1db10 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
1db20 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
1db30 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
1db40 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
1db50 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
1db60 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
1db70 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
1db80 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1db90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
1dba0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1dbb0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1dbc0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1dbd0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1dbe0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1dbf0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1dc00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1dc10 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
1dc20 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1dc30 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1dc40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1dc50 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1dc60 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1dc70 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1dc80 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1dc90 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1dca0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
1dcb0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
1dcc0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
1dcd0 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
1dce0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
1dcf0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
1dd00 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
1dd10 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
1dd20 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
1dd30 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
1dd40 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
1dd50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
1dd60 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
1dd70 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
1dd80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1dd90 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
1dda0 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
1ddb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1ddc0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
1ddd0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
1dde0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1ddf0 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
1de00 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
1de10 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1de20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
1de30 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
1de40 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
1de50 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
1de60 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
1de70 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
1de80 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
1de90 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
1dea0 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
1deb0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
1dec0 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
1ded0 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
1dee0 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
1def0 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
1df00 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
1df10 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1df20 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1df30 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1df40 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1df50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1df60 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1df70 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1df80 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1df90 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1dfa0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1dfb0 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1dfc0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1dfd0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1dfe0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1dff0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1e000 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1e010 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1e020 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1e030 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1e040 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1e050 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1e060 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1e070 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1e080 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1e090 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1e0a0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1e0b0 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1e0c0 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1e0d0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1e0e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1e0f0 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1e100 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1e110 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f   as a [SQLITE_RO
1e120 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20  LLBACK | return 
1e130 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68  code].** from th
1e140 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
1e150 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
1e160 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
1e170 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
1e180 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
1e190 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1e1a0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
1e1b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e1c0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
1e1d0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
1e1e0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
1e1f0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
1e200 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1e210 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
1e220 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
1e230 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1e240 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1e250 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
1e260 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
1e270 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
1e280 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
1e290 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
1e2a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1e2b0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
1e2c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1e2d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1e2e0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
1e2f0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
1e300 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
1e310 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
1e320 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
1e330 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
1e340 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
1e350 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1e360 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
1e370 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
1e380 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
1e390 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
1e3a0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
1e3b0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
1e3c0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
1e3d0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1e3e0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1e3f0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
1e400 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1e410 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
1e420 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
1e430 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1e440 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
1e450 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
1e460 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1e470 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
1e480 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1e490 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1e4a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1e4b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1e4c0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
1e4d0 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
1e4e0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
1e4f0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
1e500 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1e510 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
1e520 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
1e530 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
1e540 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
1e550 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
1e560 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
1e570 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
1e580 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
1e590 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
1e5a0 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
1e5b0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
1e5c0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
1e5d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e5e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e5f0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
1e600 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
1e610 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
1e620 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
1e630 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
1e640 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1e650 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e660 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e670 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
1e680 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
1e690 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e6a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e6b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e6c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1e6d0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
1e6e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1e6f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e710 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1e720 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
1e730 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e760 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1e770 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
1e780 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1e790 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e7a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e7b0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
1e7c0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
1e7d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1e7e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e7f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e800 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
1e810 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
1e820 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1e830 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e850 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
1e860 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
1e870 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1e880 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e8a0 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
1e8b0 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
1e8c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e8d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e8e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e8f0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
1e900 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
1e910 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1e920 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e940 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
1e950 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
1e960 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e970 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e990 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1e9a0 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
1e9b0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1e9c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e9d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e9e0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
1e9f0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
1ea00 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ea10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ea20 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1ea30 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
1ea40 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
1ea50 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1ea60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ea70 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1ea80 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
1ea90 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1eaa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1eab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1eac0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
1ead0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
1eae0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1eaf0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1eb00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eb10 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
1eb20 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
1eb30 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1eb40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1eb50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1eb60 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
1eb70 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
1eb80 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1eb90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1eba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ebb0 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
1ebc0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
1ebd0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
1ebe0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
1ebf0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
1ec00 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
1ec10 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
1ec20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ec30 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1ec40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ec50 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
1ec60 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
1ec70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ec80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ec90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1eca0 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
1ecb0 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
1ecc0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
1ecd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ece0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ecf0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
1ed00 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
1ed10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1ed20 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1ed30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ed40 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
1ed50 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
1ed60 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
1ed70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ed80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ed90 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
1eda0 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
1edb0 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
1edc0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1edd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
1ede0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
1edf0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
1ee00 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
1ee10 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ee20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
1ee30 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
1ee40 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
1ee50 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1ee60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ee70 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
1ee80 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
1ee90 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
1eea0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1eeb0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1eec0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1eed0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
1eee0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
1eef0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1ef00 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1ef10 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1ef20 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
1ef30 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1ef40 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1ef50 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1ef60 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
1ef70 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
1ef80 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1ef90 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
1efa0 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
1efb0 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
1efc0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
1efd0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1efe0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
1eff0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
1f000 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
1f010 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
1f020 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
1f030 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
1f040 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
1f050 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
1f060 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1f070 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1f080 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1f090 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1f0a0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1f0b0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1f0c0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1f0d0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1f0e0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1f0f0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1f100 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1f110 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
1f120 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
1f130 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
1f140 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
1f150 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
1f160 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
1f170 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
1f180 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1f190 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1f1a0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
1f1b0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1f1c0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
1f1d0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
1f1e0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1f1f0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
1f200 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
1f210 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
1f220 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
1f230 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
1f240 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
1f250 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
1f260 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
1f270 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
1f280 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
1f290 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
1f2a0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
1f2b0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
1f2c0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
1f2d0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
1f2e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1f2f0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
1f300 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
1f310 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
1f320 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
1f330 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
1f340 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
1f350 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
1f360 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1f370 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1f380 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1f390 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1f3a0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1f3b0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1f3c0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1f3d0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1f3e0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1f3f0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1f400 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1f410 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1f420 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1f430 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1f440 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1f450 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1f460 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1f470 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1f480 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1f490 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1f4a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1f4b0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1f4c0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1f4d0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1f4e0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1f4f0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1f500 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1f510 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1f520 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1f530 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1f540 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1f550 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1f560 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1f570 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1f580 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1f590 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1f5a0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1f5b0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1f5c0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1f5d0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1f5e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1f5f0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1f600 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1f610 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1f620 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1f630 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1f640 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1f650 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1f660 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1f670 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1f680 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1f690 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1f6a0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1f6b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f6c0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1f6d0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1f6e0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
1f6f0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
1f700 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
1f710 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
1f720 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1f730 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
1f740 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1f750 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1f760 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1f770 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1f780 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f790 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
1f7a0 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
1f7b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f7c0 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
1f7d0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1f7e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1f7f0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1f800 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1f810 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1f820 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
1f830 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
1f840 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
1f850 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
1f860 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1f870 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
1f880 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
1f890 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
1f8a0 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
1f8b0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1f8c0 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
1f8d0 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
1f8e0 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
1f8f0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
1f900 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
1f910 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
1f920 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
1f930 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
1f940 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
1f950 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
1f960 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
1f970 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
1f980 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
1f990 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
1f9a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f9b0 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
1f9c0 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
1f9d0 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
1f9e0 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
1f9f0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
1fa00 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
1fa10 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
1fa20 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
1fa30 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1fa40 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
1fa50 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
1fa60 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
1fa70 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
1fa80 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
1fa90 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
1faa0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1fab0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
1fac0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
1fad0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
1fae0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
1faf0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
1fb00 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
1fb10 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
1fb20 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
1fb30 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1fb40 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
1fb50 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1fb60 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1fb70 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1fb80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1fb90 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1fba0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1fbb0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1fbc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fbd0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1fbe0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1fbf0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1fc00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1fc10 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1fc20 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1fc30 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1fc40 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
1fc50 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1fc60 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1fc70 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
1fc80 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
1fc90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1fca0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
1fcb0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1fcc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1fcd0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1fce0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1fcf0 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
1fd00 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
1fd10 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
1fd20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1fd30 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1fd40 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
1fd50 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1fd60 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1fd70 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
1fd80 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1fd90 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
1fda0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
1fdb0 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
1fdc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fdd0 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
1fde0 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
1fdf0 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
1fe00 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
1fe10 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
1fe20 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
1fe30 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
1fe40 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1fe50 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
1fe60 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
1fe70 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
1fe80 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
1fe90 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
1fea0 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
1feb0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1fec0 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
1fed0 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
1fee0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
1fef0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
1ff00 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
1ff10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
1ff20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
1ff30 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1ff40 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1ff50 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
1ff60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1ff70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
1ff80 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
1ff90 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
1ffa0 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
1ffb0 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
1ffc0 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
1ffd0 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
1ffe0 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
1fff0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
20000 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
20010 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
20020 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
20030 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
20040 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
20050 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
20060 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
20070 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
20080 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
20090 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
200a0 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
200b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
200c0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
200d0 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
200e0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
200f0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
20100 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
20110 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
20120 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
20130 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
20140 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
20150 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
20160 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
20170 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
20180 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
20190 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
201a0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
201b0 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
201c0 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
201d0 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
201e0 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
201f0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
20200 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
20210 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
20220 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
20230 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
20240 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
20250 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
20260 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
20270 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
20280 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
20290 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
202a0 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
202b0 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
202c0 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
202d0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
202e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
202f0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
20300 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
20310 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
20320 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
20330 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
20340 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
20350 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
20360 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
20370 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
20380 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
20390 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
203a0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
203b0 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
203c0 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
203d0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
203e0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
203f0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
20400 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
20410 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
20420 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20430 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20440 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
20450 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
20460 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
20470 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
20480 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
20490 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
204a0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
204b0 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
204c0 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
204d0 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
204e0 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
204f0 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
20500 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
20510 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
20520 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
20530 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
20540 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
20550 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
20560 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
20570 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
20580 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
20590 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
205a0 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
205b0 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
205c0 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
205d0 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
205e0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
205f0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
20600 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
20610 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
20620 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
20630 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
20640 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
20650 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
20660 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
20670 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
20680 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
20690 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
206a0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
206b0 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
206c0 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
206d0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
206e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
206f0 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
20700 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
20710 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
20720 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20730 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
20740 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
20750 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
20760 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
20770 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
20780 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
20790 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
207a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
207b0 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
207c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
207d0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
207e0 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
207f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20800 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
20810 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
20820 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
20830 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
20840 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
20850 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
20860 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
20870 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
20880 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
20890 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
208a0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
208b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
208c0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
208d0 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
208e0 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
208f0 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
20900 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
20910 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
20920 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
20930 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
20940 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
20950 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
20960 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
20970 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
20980 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
20990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
209a0 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
209b0 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
209c0 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
209d0 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
209e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
209f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
20a00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20a10 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
20a20 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
20a30 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
20a40 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
20a50 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
20a60 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
20a70 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
20a80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
20a90 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
20aa0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
20ab0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
20ac0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
20ad0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
20ae0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
20af0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
20b00 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
20b10 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
20b20 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
20b30 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
20b40 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
20b50 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
20b60 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
20b70 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
20b80 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
20b90 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
20ba0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20bb0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
20bc0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20bd0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
20be0 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
20bf0 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
20c00 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
20c10 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
20c20 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
20c30 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
20c40 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
20c50 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
20c60 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
20c70 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
20c80 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
20c90 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
20ca0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
20cb0 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
20cc0 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
20cd0 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
20ce0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
20cf0 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
20d00 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
20d10 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
20d20 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
20d30 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
20d40 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
20d50 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
20d60 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
20d70 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
20d80 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
20d90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20da0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
20db0 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
20dc0 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
20dd0 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
20de0 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
20df0 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
20e00 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
20e10 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
20e20 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
20e30 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
20e40 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
20e50 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
20e60 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
20e70 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
20e80 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
20e90 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
20ea0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
20eb0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
20ec0 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
20ed0 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
20ee0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
20ef0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20f00 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
20f10 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
20f20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
20f30 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
20f40 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
20f50 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
20f60 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
20f70 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
20f80 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
20f90 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
20fa0 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
20fb0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
20fc0 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
20fd0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
20fe0 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
20ff0 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
21000 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
21010 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
21020 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
21030 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
21040 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
21050 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
21060 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
21070 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
21080 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
21090 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
210a0 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
210b0 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
210c0 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
210d0 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
210e0 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
210f0 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
21100 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
21110 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
21120 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
21130 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
21140 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
21150 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
21160 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
21170 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
21180 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
21190 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
211a0 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
211b0 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
211c0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
211d0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
211e0 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
211f0 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
21200 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
21210 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
21220 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
21230 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
21240 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
21250 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
21260 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
21270 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
21280 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
21290 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
212a0 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
212b0 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
212c0 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
212d0 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
212e0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
212f0 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
21300 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
21310 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
21320 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
21330 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68   ^On windows, th
21340 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
21350 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
21360 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
21370 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
21380 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a  on (e.g. "C:")..
21390 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
213a0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
213b0 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
213c0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
213d0 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
213e0 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
213f0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
21400 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
21410 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
21420 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
21430 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
21440 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
21450 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
21460 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
21470 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
21480 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
21490 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
214a0 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
214b0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
214c0 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
214d0 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
214e0 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
214f0 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
21500 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
21510 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
21520 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
21530 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
21540 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
21550 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
21560 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
21570 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
21580 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
21590 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
215a0 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
215b0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
215c0 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
215d0 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
215e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
215f0 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
21600 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
21610 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
21620 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
21630 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
21640 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
21650 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
21660 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
21670 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
21680 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
21690 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
216a0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
216b0 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
216c0 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
216d0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
216e0 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
216f0 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
21700 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
21710 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
21720 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
21730 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
21740 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
21750 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
21760 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
21770 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
21780 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
21790 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
217a0 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
217b0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
217c0 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
217d0 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
217e0 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
217f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
21800 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
21810 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
21820 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
21830 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
21840 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
21850 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
21860 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
21870 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
21880 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
21890 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
218a0 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
218b0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
218c0 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
218d0 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
218e0 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
218f0 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
21900 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
21910 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
21920 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
21930 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
21940 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
21950 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
21960 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
21970 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
21980 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
21990 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
219a0 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
219b0 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
219c0 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
219d0 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
219e0 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
219f0 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
21a00 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
21a10 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
21a20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
21a30 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
21a40 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
21a50 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
21a60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21a70 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
21a80 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
21a90 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
21aa0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
21ab0 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
21ac0 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
21ad0 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
21ae0 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
21af0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
21b00 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
21b10 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
21b20 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
21b30 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
21b40 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
21b50 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
21b60 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
21b70 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
21b80 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
21b90 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
21ba0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
21bb0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
21bc0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
21bd0 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
21be0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21bf0 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
21c00 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
21c10 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
21c20 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
21c30 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
21c40 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
21c50 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
21c60 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
21c70 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
21c80 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
21c90 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
21ca0 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
21cb0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
21cc0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
21cd0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
21ce0 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
21cf0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
21d00 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
21d10 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
21d20 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
21d30 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
21d40 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
21d50 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
21d60 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
21d70 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
21d80 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
21d90 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
21da0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
21db0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
21dc0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
21dd0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
21de0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
21df0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
21e00 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
21e10 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
21e20 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
21e30 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
21e40 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
21e50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
21e60 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
21e70 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
21e80 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
21e90 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
21ea0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
21eb0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
21ec0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
21ed0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
21ee0 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
21ef0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
21f00 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
21f10 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
21f20 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21f30 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
21f40 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
21f50 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
21f60 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
21f70 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
21f80 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
21f90 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
21fa0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
21fb0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
21fc0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
21fd0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
21fe0 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
21ff0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
22000 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
22010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
22020 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
22030 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
22040 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
22050 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
22060 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
22070 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
22080 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
22090 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
220a0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
220b0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
220c0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
220d0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
220e0 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
220f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
22100 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
22110 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
22120 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
22130 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
22140 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
22150 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
22160 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
22170 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
22180 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
22190 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
221a0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
221b0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
221c0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
221d0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
221e0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
221f0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
22200 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
22210 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
22220 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
22230 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
22240 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
22250 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
22260 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
22270 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a  x-nolock <td>.**
22280 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
22290 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
222a0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
222b0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
222c0 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20  nix-nolock"..** 
222d0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
222e0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
222f0 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
22300 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
22310 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
22320 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
22330 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
22340 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
22350 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
22360 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
22370 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
22380 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
22390 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
223a0 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
223b0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
223c0 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
223d0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
223e0 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
223f0 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
22400 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
22410 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
22420 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
22430 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
22440 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
22450 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
22460 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
22470 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
22480 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
22490 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
224a0 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
224b0 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
224c0 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
224d0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
224e0 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
224f0 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
22500 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
22510 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
22520 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
22530 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
22540 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
22550 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
22560 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
22570 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
22580 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
22590 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
225a0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
225b0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
225c0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
225d0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
225e0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
225f0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
22600 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
22610 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
22620 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
22630 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
22640 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
22650 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
22660 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
22670 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
22680 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
22690 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
226a0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
226b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
226c0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
226d0 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
226e0 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
226f0 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
22700 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
22710 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
22720 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
22730 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
22740 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
22750 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
22760 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
22770 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
22780 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
22790 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
227a0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
227b0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
227c0 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71  ctory].*/.int sq
227d0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
227e0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
227f0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
22800 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
22810 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
22820 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
22830 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
22840 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
22850 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
22860 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
22870 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
22880 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
22890 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
228a0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
228b0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
228c0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
228d0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
228e0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
228f0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
22900 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
22910 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
22920 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
22930 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
22940 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
22950 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
22960 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
22970 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
22980 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
22990 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
229a0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
229b0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
229c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
229d0 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
229e0 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
229f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
22a00 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
22a10 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
22a20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
22a30 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
22a40 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
22a50 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
22a60 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
22a70 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
22a80 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
22a90 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
22aa0 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
22ab0 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
22ac0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
22ad0 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
22ae0 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
22af0 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
22b00 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
22b10 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
22b20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
22b30 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
22b40 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
22b50 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
22b60 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
22b70 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
22b80 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
22b90 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
22ba0 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
22bb0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
22bc0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
22bd0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
22be0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
22bf0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
22c00 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
22c10 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
22c20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
22c30 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
22c40 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
22c50 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
22c60 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
22c70 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
22c80 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
22c90 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
22ca0 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
22cb0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
22cc0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
22cd0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
22ce0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
22cf0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
22d00 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
22d10 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
22d20 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
22d30 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
22d40 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
22d50 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
22d60 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
22d70 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
22d80 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
22d90 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
22da0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
22db0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
22dc0 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
22dd0 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
22de0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
22df0 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
22e00 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
22e10 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
22e20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
22e30 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
22e40 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
22e50 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
22e60 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
22e70 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
22e80 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
22e90 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
22ea0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
22eb0 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
22ec0 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
22ed0 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
22ee0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
22ef0 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
22f00 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
22f10 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
22f20 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
22f30 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
22f40 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
22f50 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
22f60 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
22f70 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
22f80 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
22f90 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
22fa0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
22fb0 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
22fc0 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
22fd0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
22fe0 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
22ff0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
23000 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
23010 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
23020 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
23030 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
23040 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
23050 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
23060 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
23070 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
23080 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
23090 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
230a0 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
230b0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
230c0 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
230d0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
230e0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
230f0 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
23100 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
23110 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
23120 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
23130 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
23140 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
23150 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
23160 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
23170 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
23180 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
23190 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
231a0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
231b0 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
231c0 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ble..*/.const ch
231d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
231e0 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
231f0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
23200 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
23210 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ram);.int sqlite
23220 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
23230 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
23240 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
23250 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
23260 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  t);.sqlite3_int6
23270 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
23280 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
23290 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
232a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
232b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
232c0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
232d0 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
232e0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
232f0 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
23300 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
23310 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
23320 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
23330 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
23340 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
23350 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
23360 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
23370 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
23380 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
23390 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
233a0 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
233b0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
233c0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
233d0 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
233e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
233f0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
23400 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
23410 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
23420 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
23430 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
23440 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
23450 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
23460 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
23470 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
23480 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
23490 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
234a0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
234b0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
234c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
234d0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
234e0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
234f0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
23500 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
23510 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
23520 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
23530 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
23540 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
23550 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
23560 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
23570 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
23580 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
23590 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
235a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
235b0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
235c0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
235d0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
235e0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
235f0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
23600 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
23610 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
23620 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
23630 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
23640 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
23650 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
23660 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
23670 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
23680 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
23690 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
236a0 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
236b0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
236c0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
236d0 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
236e0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
236f0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
23700 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
23710 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
23720 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
23730 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
23740 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
23750 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
23760 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
23770 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
23780 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
23790 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
237a0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
237b0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
237c0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
237d0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
237e0 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
237f0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
23800 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
23810 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
23820 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
23830 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
23840 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
23850 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
23860 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
23870 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
23880 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
23890 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
238a0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
238b0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
238c0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
238d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
238e0 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
238f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
23900 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
23910 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
23920 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
23930 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
23940 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
23950 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
23960 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
23970 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
23980 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
23990 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
239a0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
239b0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
239c0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
239d0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
239e0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
239f0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
23a00 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
23a10 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
23a20 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
23a30 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
23a40 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
23a50 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
23a60 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
23a70 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
23a80 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
23a90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
23aa0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
23ab0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
23ac0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
23ad0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
23ae0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
23af0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
23b00 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
23b10 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
23b20 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
23b30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
23b40 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
23b50 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
23b60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23b70 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
23b80 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
23b90 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
23ba0 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
23bb0 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
23bc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
23bd0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
23be0 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
23bf0 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
23c00 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
23c10 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
23c20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
23c30 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
23c40 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
23c50 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
23c60 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
23c70 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
23c80 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
23c90 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
23ca0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
23cb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23cc0 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
23cd0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
23ce0 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
23cf0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
23d00 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
23d10 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
23d20 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
23d30 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
23d40 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
23d50 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
23d60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
23d70 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
23d80 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
23d90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
23da0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
23db0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
23dc0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
23dd0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
23de0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
23df0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
23e00 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
23e10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
23e20 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
23e30 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
23e40 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
23e50 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
23e60 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
23e70 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
23e80 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
23e90 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
23ea0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
23eb0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
23ec0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
23ed0 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
23ee0 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
23ef0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
23f00 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
23f10 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
23f20 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
23f30 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
23f40 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
23f50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
23f60 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
23f70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23f80 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
23f90 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
23fa0 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
23fb0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
23fc0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
23fd0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
23fe0 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
23ff0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
24000 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
24010 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
24020 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
24030 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
24040 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
24050 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
24060 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
24070 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
24080 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
24090 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
240a0 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
240b0 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
240c0 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
240d0 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
240e0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
240f0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
24100 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
24110 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
24120 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
24130 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
24140 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
24150 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
24160 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
24170 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
24180 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
24190 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
241a0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
241b0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
241c0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
241d0 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
241e0 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
241f0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
24200 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
24210 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
24220 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
24230 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
24240 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
24250 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
24260 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
24270 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
24280 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
24290 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
242a0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
242b0 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
242c0 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
242d0 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
242e0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
242f0 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
24300 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
24310 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
24320 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
24330 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
24340 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
24350 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
24360 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
24370 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
24380 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
24390 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
243a0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
243b0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
243c0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
243d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
243e0 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
243f0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
24400 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
24410 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
24420 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
24430 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
24440 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
24450 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
24460 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
24470 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
24480 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
24490 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
244a0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
244b0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
244c0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
244d0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
244e0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
244f0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
24500 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
24510 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
24520 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
24530 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
24540 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
24550 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
24560 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
24570 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
24580 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
24590 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
245a0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
245b0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
245c0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
245d0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
245e0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
245f0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
24600 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
24610 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
24620 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
24630 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
24640 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
24650 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
24660 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
24670 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
24680 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
24690 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
246a0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
246b0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
246c0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
246d0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
246e0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
246f0 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
24700 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
24710 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
24720 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
24730 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
24740 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
24750 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
24760 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
24770 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
24780 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
24790 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
247a0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
247b0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
247c0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
247d0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
247e0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
247f0 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
24800 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
24810 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24820 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
24830 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
24840 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
24850 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
24860 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
24870 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
24880 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
24890 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
248a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
248b0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
248c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
248d0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
248e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
248f0 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
24900 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
24910 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
24920 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24930 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
24940 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
24950 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
24960 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
24970 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
24980 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
24990 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
249a0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
249b0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
249c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
249d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
249e0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
249f0 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
24a00 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
24a10 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24a20 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
24a30 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
24a40 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
24a50 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
24a60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
24a70 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
24a80 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
24a90 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
24aa0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
24ab0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
24ac0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
24ad0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
24ae0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
24af0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24b00 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
24b10 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
24b20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
24b30 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
24b40 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
24b50 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
24b60 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
24b70 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
24b80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
24b90 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
24ba0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
24bb0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
24bc0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
24bd0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
24be0 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
24bf0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
24c00 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
24c10 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
24c20 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
24c30 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
24c40 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
24c50 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24c60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
24c70 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
24c80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
24c90 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
24ca0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24cb0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
24cc0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
24cd0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
24ce0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24cf0 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
24d00 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24d10 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
24d20 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
24d30 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
24d40 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
24d50 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
24d60 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24d70 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
24d80 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
24d90 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24da0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
24db0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
24dc0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
24dd0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
24de0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
24df0 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
24e00 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
24e10 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
24e20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
24e30 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
24e40 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
24e50 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
24e60 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
24e70 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
24e80 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
24e90 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
24ea0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
24eb0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
24ec0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
24ed0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
24ee0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
24ef0 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
24f00 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
24f10 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
24f20 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
24f30 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  ers.</dd>)^.** <
24f40 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
24f50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
24f60 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
24f70 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
24f80 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
24f90 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
24fa0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
24fb0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
24fc0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
24fd0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
24fe0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24ff0 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
25000 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
25010 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25020 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
25030 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
25040 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25050 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
25060 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
25070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25080 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
25090 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
250a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
250b0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
250c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
250d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
250e0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
250f0 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
25100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25110 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
25120 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
25130 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
25140 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
25150 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
25160 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
25170 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
25180 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
25190 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
251a0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
251b0 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
251c0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
251d0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
251e0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
251f0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
25200 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
25210 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
25220 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
25230 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
25240 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
25250 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25260 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
25270 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
25280 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
25290 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
252a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
252b0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
252c0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
252d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
252e0 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
252f0 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
25300 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
25310 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
25320 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
25330 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
25340 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
25350 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
25360 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
25370 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25380 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
25390 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
253a0 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
253b0 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
253c0 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
253d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
253e0 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
253f0 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
25400 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
25410 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
25420 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
25430 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
25440 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
25450 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
25460 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
25470 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
25480 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
25490 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
254a0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
254b0 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
254c0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
254d0 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
254e0 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
254f0 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
25500 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
25510 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
25520 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
25530 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
25540 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
25550 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
25560 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
25570 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
25580 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
25590 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
255a0 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
255b0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
255c0 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
255d0 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
255e0 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
255f0 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
25600 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
25610 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
25620 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
25630 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
25640 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20  erminator bytes 
25650 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51  as this saves SQ
25660 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67  Lite from having
25670 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f   to.** make a co
25680 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20  py of the input 
25690 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
256a0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
256b0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
256c0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
256d0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
256e0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
256f0 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
25700 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
25710 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
25720 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
25730 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
25740 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
25750 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
25760 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
25770 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
25780 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
25790 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
257a0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
257b0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
257c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
257d0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
257e0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
257f0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
25800 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
25810 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
25820 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
25830 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
25840 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
25850 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
25860 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
25870 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
25880 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
25890 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
258a0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
258b0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
258c0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
258d0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
258e0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
258f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
25900 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
25910 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
25920 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
25930 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
25940 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
25950 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
25960 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
25970 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
25980 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
25990 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
259a0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
259b0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
259c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
259d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
259e0 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
259f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25a00 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
25a10 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
25a20 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
25a30 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
25a40 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
25a50 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
25a60 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
25a70 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
25a80 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
25a90 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
25aa0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
25ab0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
25ac0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25ad0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
25ae0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
25af0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
25b00 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
25b10 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
25b20 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
25b30 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
25b40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
25b50 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
25b60 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
25b70 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
25b80 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
25b90 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
25ba0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
25bb0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
25bc0 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
25bd0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
25be0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
25bf0 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
25c00 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
25c10 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
25c20 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
25c30 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
25c40 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
25c50 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
25c60 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
25c70 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
25c80 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
25c90 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
25ca0 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
25cb0 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
25cc0 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
25cd0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
25ce0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
25cf0 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
25d00 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
25d10 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
25d20 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
25d30 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
25d40 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
25d50 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
25d60 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
25d70 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
25d80 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
25d90 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
25da0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
25db0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
25dc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
25dd0 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
25de0 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
25df0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
25e00 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
25e10 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
25e20 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
25e30 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
25e40 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
25e50 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
25e60 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
25e70 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
25e80 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
25e90 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
25ea0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
25eb0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
25ec0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
25ed0 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
25ee0 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
25ef0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
25f00 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
25f10 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
25f20 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
25f30 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
25f40 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
25f50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
25f60 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
25f70 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
25f80 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
25f90 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
25fa0 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
25fb0 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
25fc0 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
25fd0 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
25fe0 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
25ff0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
26000 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
26010 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
26020 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
26030 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
26040 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
26050 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
26060 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
26070 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
26080 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
26090 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
260a0 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
260b0 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
260c0 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
260d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
260e0 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
260f0 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
26100 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
26110 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
26120 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
26130 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
26140 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
26150 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
26160 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
26170 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
26180 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
26190 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
261a0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
261b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
261c0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
261d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
261e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
261f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
26200 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
26210 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
26220 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
26230 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
26240 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
26250 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
26260 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
26270 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
26280 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
26290 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
262a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
262b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
262c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
262d0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
262e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
262f0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
26300 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
26310 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
26320 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
26330 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
26340 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
26350 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
26360 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
26370 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
26380 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
26390 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
263a0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
263b0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
263c0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
263d0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
263e0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
263f0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
26400 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
26410 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
26420 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
26430 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
26440 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
26450 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
26460 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
26470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26480 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
26490 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
264a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
264b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
264c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
264d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
264e0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
264f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
26500 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
26510 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
26520 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
26530 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
26540 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
26550 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
26560 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
26570 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
26580 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
26590 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
265a0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
265b0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
265c0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
265d0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
265e0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
265f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
26600 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
26610 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
26620 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
26630 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
26640 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
26650 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
26660 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
26670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
26680 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
26690 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54  ent SQL.**.** ^T
266a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
266b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
266c0 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
266d0 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
266e0 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
266f0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
26700 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26710 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
26720 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
26730 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
26740 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
26750 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
26760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26770 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  _v2()]..*/.const
26780 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
26790 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
267a0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
267b0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
267c0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
267d0 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
267e0 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a  he Database.**.*
267f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
26800 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
26810 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26820 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
26830 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
26840 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
26850 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
26860 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
26870 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
26880 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
26890 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
268a0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
268b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
268c0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
268d0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
268e0 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
268f0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
26900 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
26910 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
26920 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
26930 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
26940 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
26950 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
26960 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
26970 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
26980 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
26990 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
269a0 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
269b0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
269c0 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
269d0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
269e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
269f0 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
26a00 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
26a10 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
26a20 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
26a30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
26a40 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
26a50 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
26a60 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
26a70 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
26a80 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
26a90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
26aa0 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
26ab0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
26ac0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
26ad0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
26ae0 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
26af0 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
26b00 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
26b10 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
26b20 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
26b30 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
26b40 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
26b50 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
26b60 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
26b70 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
26b80 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
26b90 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
26ba0 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
26bb0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
26bc0 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
26bd0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
26be0 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
26bf0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
26c00 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
26c10 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
26c20 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
26c30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
26c40 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
26c50 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
26c60 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
26c70 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
26c80 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
26c90 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
26ca0 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
26cb0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
26cc0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
26cd0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
26ce0 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
26cf0 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71   disk..*/.int sq
26d00 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
26d10 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
26d20 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
26d30 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
26d40 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
26d50 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
26d60 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a   Been Reset.**.*
26d70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
26d80 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
26d90 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
26da0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
26db0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
26dc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
26dd0 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
26de0 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
26df0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
26e00 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
26e10 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d  s not run to com
26e20 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68  pletion and/or h
26e30 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20  as not .** been 
26e40 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
26e50 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
26e60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
26e70 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
26e80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26e90 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
26ea0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
26eb0 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
26ec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
26ed0 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
26ee0 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
26ef0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26f00 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
26f10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
26f20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
26f30 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
26f40 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
26f50 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
26f60 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
26f70 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
26f80 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
26f90 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
26fa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26fb0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
26fc0 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
26fd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
26fe0 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
26ff0 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
27000 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
27010 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
27020 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
27030 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
27040 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
27050 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
27060 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
27070 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
27080 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27090 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
270a0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
270b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
270c0 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
270d0 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
270e0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
270f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27100 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
27110 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
27120 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
27130 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
27140 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
27150 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
27160 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
27170 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
27180 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
27190 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
271a0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
271b0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
271c0 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
271d0 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
271e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
271f0 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
27200 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
27210 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
27220 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
27230 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
27240 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
27250 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
27260 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
27270 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
27280 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
27290 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
272a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
272b0 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
272c0 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
272d0 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
272e0 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
272f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27300 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
27310 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
27320 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
27330 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
27340 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
27350 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
27360 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
27370 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
27380 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
27390 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
273a0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
273b0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
273c0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
273d0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
273e0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
273f0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
27400 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
27410 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
27420 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
27430 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
27440 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
27450 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
27460 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
27470 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
27480 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
27490 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
274a0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
274b0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
274c0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
274d0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
274e0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
274f0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
27500 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
27510 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
27520 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
27530 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
27540 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
27550 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
27560 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
27570 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
27580 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
27590 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
275a0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
275b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
275c0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
275d0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
275e0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
275f0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
27600 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
27610 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
27620 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
27630 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
27640 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
27650 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
27660 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27670 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
27680 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
27690 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
276a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
276b0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
276c0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
276d0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
276e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
276f0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
27700 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
27710 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
27720 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
27730 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27740 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
27750 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
27760 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
27770 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
27780 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27790 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
277a0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
277b0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
277c0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
277d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
277e0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
277f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
27800 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
27810 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
27820 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
27830 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
27840 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
27850 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
27860 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27870 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
27880 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
27890 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
278a0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
278b0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
278c0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
278d0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
278e0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
278f0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
27900 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
27910 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
27920 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
27930 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
27940 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
27950 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
27960 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
27970 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
27980 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
27990 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
279a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
279b0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
279c0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
279d0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
279e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
279f0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
27a00 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
27a10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
27a20 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
27a30 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
27a40 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
27a50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
27a60 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
27a70 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
27a80 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
27a90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
27aa0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
27ab0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
27ac0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
27ad0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
27ae0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
27af0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
27b00 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
27b10 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
27b20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
27b30 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
27b40 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
27b50 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
27b60 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
27b70 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
27b80 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
27b90 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
27ba0 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
27bb0 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
27bc0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
27bd0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
27be0 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
27bf0 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
27c00 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
27c10 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
27c20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
27c30 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
27c40 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
27c50 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
27c60 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
27c70 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
27c80 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
27c90 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
27ca0 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
27cb0 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
27cc0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
27cd0 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
27ce0 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
27cf0 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
27d00 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
27d10 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
27d20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
27d30 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
27d40 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
27d50 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
27d60 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
27d70 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
27d80 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
27d90 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
27da0 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
27db0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
27dc0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
27dd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
27de0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
27df0 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
27e00 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
27e10 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
27e20 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
27e30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27e40 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
27e50 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
27e60 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
27e70 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
27e80 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
27e90 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
27ea0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
27eb0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
27ec0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
27ed0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
27ee0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
27ef0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
27f00 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
27f10 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
27f20 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
27f30 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
27f40 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
27f50 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
27f60 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
27f70 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
27f80 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
27f90 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
27fa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
27fb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
27fc0 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
27fd0 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
27fe0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
27ff0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
28000 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
28010 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
28020 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
28030 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
28040 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
28050 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
28060 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
28070 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
28080 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
28090 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
280a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
280b0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
280c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
280d0 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
280e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
280f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
28100 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
28110 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
28120 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
28130 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
28140 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
28150 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
28160 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
28170 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
28180 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
28190 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
281a0 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
281b0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
281c0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
281d0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
281e0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
281f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
28200 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
28210 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
28220 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
28230 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
28240 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
28250 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
28260 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
28270 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
28280 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
28290 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
282a0 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
282b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
282c0 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
282d0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
282e0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
282f0 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
28300 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
28310 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
28320 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
28330 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
28340 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
28350 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
28360 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
28370 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
28380 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
28390 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
283a0 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
283b0 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
283c0 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
283d0 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
283e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
283f0 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20  t16() then that 
28400 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
28410 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
28420 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
28430 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
28440 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
28450 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
28460 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
28470 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
28480 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
28490 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
284a0 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
284b0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
284c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
284d0 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
284e0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
284f0 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
28500 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
28510 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
28520 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
28530 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
28540 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
28550 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
28560 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
28570 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
28580 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28590 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
285a0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
285b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
285c0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
285d0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
285e0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
285f0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
28600 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
28610 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
28620 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
28630 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
28640 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
28650 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
28660 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
28670 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
28680 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
28690 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
286a0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
286b0 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
286c0 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
286d0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
286e0 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
286f0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
28700 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
28710 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
28720 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
28730 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
28740 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
28750 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
28760 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
28770 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
28780 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
28790 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
287a0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
287b0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
287c0 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
287d0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
287e0 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
287f0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
28800 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
28810 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
28820 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28830 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
28840 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
28850 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
28860 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
28870 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
28880 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
28890 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
288a0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
288b0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
288c0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
288d0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
288e0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
288f0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
28900 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
28910 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
28920 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
28930 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
28940 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
28950 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
28960 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
28970 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
28980 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
28990 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
289a0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
289b0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
289c0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
289d0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
289e0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
289f0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
28a00 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
28a10 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
28a20 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
28a30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28a40 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
28a50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
28a60 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
28a70 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
28a80 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
28a90 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
28aa0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28ab0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
28ac0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
28ad0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
28ae0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
28af0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
28b00 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
28b10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28b20 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
28b30 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
28b40 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
28b50 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
28b60 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
28b70 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
28b80 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
28b90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
28ba0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
28bb0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
28bc0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
28bd0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
28be0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28bf0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
28c00 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
28c10 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
28c20 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
28c30 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
28c40 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
28c50 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
28c60 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
28c70 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
28c80 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
28c90 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
28ca0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
28cb0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
28cc0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
28cd0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
28ce0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28cf0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
28d00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28d10 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
28d20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
28d30 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
28d40 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
28d50 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
28d60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28d70 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
28d80 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
28d90 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
28da0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
28db0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28dc0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
28dd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
28de0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28df0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
28e00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
28e10 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
28e20 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
28e30 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
28e40 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
28e50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
28e60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
28e70 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
28e80 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
28e90 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
28ea0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
28eb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28ec0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
28ed0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
28ee0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
28ef0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
28f00 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28f10 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
28f20 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
28f30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28f40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
28f50 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
28f60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
28f70 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
28f80 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
28f90 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
28fa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
28fb0 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
28fc0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
28fd0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
28fe0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
28ff0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29000 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
29010 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
29020 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
29030 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
29040 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
29050 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
29060 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
29070 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
29080 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
29090 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
290a0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
290b0 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
290c0 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
290d0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
290e0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
290f0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
29100 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
29110 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
29120 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
29130 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
29140 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
29150 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
29160 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
29170 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
29180 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
29190 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
291a0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
291b0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
291c0 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
291d0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
291e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
291f0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
29200 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29210 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
29220 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
29230 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29240 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
29250 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
29260 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
29270 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
29280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
29290 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
292a0 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
292b0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
292c0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
292d0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
292e0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
292f0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
29300 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
29310 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29320 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
29330 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
29340 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
29350 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
29360 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
29370 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
29380 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
29390 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
293a0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
293b0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
293c0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
293d0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
293e0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
293f0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
29400 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
29410 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
29420 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
29430 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
29440 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
29450 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
29460 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
29470 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
29480 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
29490 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
294a0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
294b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
294c0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
294d0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
294e0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
294f0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
29500 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
29510 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
29520 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
29530 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
29540 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
29550 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
29560 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
29570 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
29580 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
29590 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
295a0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
295b0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
295c0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
295d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
295e0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
295f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
29600 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
29610 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
29620 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
29630 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
29640 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29650 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
29660 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29670 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
29680 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
29690 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
296a0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
296b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
296c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
296d0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
296e0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
296f0 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
29700 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
29710 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
29720 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
29730 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
29740 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
29750 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
29760 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
29770 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
29780 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
29790 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
297a0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
297b0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
297c0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
297d0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
297e0 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
297f0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
29800 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
29810 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
29820 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
29830 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
29840 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
29850 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
29860 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
29870 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
29880 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
29890 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
298a0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
298b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
298c0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
298d0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
298e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
298f0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
29900 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29910 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
29920 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
29930 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
29940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
29950 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
29960 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
29970 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
29980 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
29990 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
299a0 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
299b0 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
299c0 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
299d0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
299e0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
299f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29a00 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
29a10 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
29a20 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
29a30 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
29a40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29a50 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
29a60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
29a70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29a80 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
29a90 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
29aa0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
29ab0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
29ac0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
29ad0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
29ae0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
29af0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29b00 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
29b10 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
29b20 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
29b30 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
29b40 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
29b50 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
29b60 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
29b70 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
29b80 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
29b90 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
29ba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
29bb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
29bc0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
29bd0 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
29be0 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
29bf0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
29c00 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
29c10 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
29c20 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
29c30 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
29c40 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
29c50 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
29c60 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
29c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
29c80 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
29c90 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
29ca0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
29cb0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
29cc0 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
29cd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
29ce0 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
29cf0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
29d00 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
29d10 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
29d20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
29d30 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
29d40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
29d50 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
29d60 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
29d70 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
29d80 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
29d90 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
29da0 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
29db0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
29dc0 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
29dd0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
29de0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
29df0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
29e00 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
29e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
29e20 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
29e30 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
29e40 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
29e50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
29e60 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
29e70 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
29e80 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
29e90 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
29ea0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
29eb0 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
29ec0 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
29ed0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
29ee0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
29ef0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29f00 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
29f10 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
29f20 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
29f30 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
29f40 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
29f50 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
29f60 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
29f70 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
29f80 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
29f90 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
29fa0 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
29fb0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
29fc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
29fd0 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
29fe0 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
29ff0 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
2a000 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
2a010 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
2a020 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
2a030 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
2a040 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
2a050 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
2a060 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
2a070 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
2a080 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
2a090 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
2a0a0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
2a0b0 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
2a0c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a0d0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
2a0e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2a0f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2a100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2a110 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2a120 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
2a130 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
2a140 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
2a150 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
2a160 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2a170 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
2a180 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
2a190 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
2a1a0 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
2a1b0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
2a1c0 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
2a1d0 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
2a1e0 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
2a1f0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2a200 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
2a210 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2a220 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
2a230 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
2a240 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
2a250 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
2a260 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2a270 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
2a280 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
2a290 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
2a2a0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
2a2b0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2a2c0 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
2a2d0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
2a2e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2a2f0 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
2a300 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2a310 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
2a320 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
2a330 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a340 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
2a350 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2a360 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2a370 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2a380 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2a390 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2a3a0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2a3b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a3c0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2a3d0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2a3e0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
2a3f0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
2a400 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
2a410 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
2a420 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
2a430 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
2a440 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
2a450 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
2a460 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
2a470 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
2a480 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
2a490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2a4a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2a4b0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
2a4c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2a4d0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
2a4e0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2a4f0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2a500 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
2a510 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
2a520 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
2a530 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
2a540 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
2a550 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2a560 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
2a570 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
2a580 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
2a590 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
2a5a0 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
2a5b0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2a5c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2a5d0 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
2a5e0 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
2a5f0 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
2a600 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
2a610 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
2a620 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
2a630 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
2a640 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
2a650 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
2a660 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2a670 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
2a680 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
2a690 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
2a6a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
2a6b0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
2a6c0 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
2a6d0 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
2a6e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
2a6f0 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
2a700 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
2a710 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
2a720 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
2a730 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
2a740 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
2a750 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
2a760 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
2a770 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
2a780 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
2a790 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
2a7a0 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
2a7b0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2a7c0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2a7d0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2a7e0 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2a7f0 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2a800 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2a810 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
2a820 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2a830 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2a840 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2a850 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
2a860 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
2a870 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
2a880 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
2a890 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2a8a0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
2a8b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
2a8c0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2a8d0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2a8e0 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
2a8f0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2a900 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
2a910 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
2a920 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
2a930 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
2a940 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
2a950 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
2a960 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2a970 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2a980 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2a990 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2a9a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2a9b0 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
2a9c0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2a9d0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2a9e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2a9f0 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
2aa00 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2aa10 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2aa20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2aa30 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2aa40 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2aa50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2aa60 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
2aa70 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2aa80 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2aa90 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2aaa0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
2aab0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2aac0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2aad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2aae0 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
2aaf0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2ab00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2ab10 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
2ab20 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
2ab30 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
2ab40 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2ab50 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2ab60 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
2ab70 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
2ab80 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
2ab90 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
2aba0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2abb0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
2abc0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
2abd0 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
2abe0 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
2abf0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2ac00 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
2ac10 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
2ac20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
2ac30 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
2ac40 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
2ac50 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2ac60 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2ac70 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
2ac80 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2ac90 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
2aca0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2acb0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
2acc0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
2acd0 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
2ace0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2acf0 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
2ad00 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2ad10 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
2ad20 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
2ad30 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
2ad40 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2ad50 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2ad60 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
2ad70 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
2ad80 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
2ad90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
2ada0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
2adb0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
2adc0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
2add0 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
2ade0 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
2adf0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
2ae00 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
2ae10 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
2ae20 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
2ae30 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
2ae40 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
2ae50 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
2ae60 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
2ae70 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
2ae80 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
2ae90 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
2aea0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
2aeb0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
2aec0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
2aed0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
2aee0 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
2aef0 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
2af00 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
2af10 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
2af20 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
2af30 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2af40 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
2af50 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
2af60 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
2af70 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
2af80 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
2af90 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2afa0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2afb0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2afc0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2afd0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2afe0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2aff0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b010 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
2b020 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2b030 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2b040 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2b050 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2b060 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2b070 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b080 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2b090 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2b0a0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2b0b0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2b0c0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2b0d0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2b0e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2b0f0 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2b100 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2b110 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2b120 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2b130 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2b140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2b150 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2b160 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2b170 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2b180 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2b190 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2b1a0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2b1b0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2b1c0 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2b1d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2b1e0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2b1f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b200 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2b210 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2b220 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2b230 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2b240 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2b250 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2b260 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2b270 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2b280 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2b290 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2b2a0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2b2b0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2b2c0 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2b2d0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2b2e0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2b2f0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2b300 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2b310 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2b320 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2b330 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2b340 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2b350 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2b360 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2b370 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2b380 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2b390 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2b3a0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2b3b0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2b3c0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2b3d0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2b3e0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2b3f0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2b400 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2b410 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2b420 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2b430 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2b440 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2b450 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2b460 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2b470 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2b480 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2b490 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2b4a0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2b4b0 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2b4c0 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2b4d0 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2b4e0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2b4f0 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2b500 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2b510 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2b520 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2b530 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2b540 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2b550 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2b560 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2b570 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2b580 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2b590 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2b5a0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2b5b0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2b5c0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2b5d0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2b5e0 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2b5f0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2b600 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2b610 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2b620 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2b630 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2b640 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2b650 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2b660 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2b670 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2b680 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2b690 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2b6a0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2b6b0 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2b6c0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2b6d0 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2b6e0 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2b6f0 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2b700 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2b710 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2b720 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2b730 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2b740 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2b750 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2b760 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2b770 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2b780 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2b790 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2b7a0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2b7b0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2b7c0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2b7d0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2b7e0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2b7f0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2b800 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2b810 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2b820 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2b830 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2b840 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2b850 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2b860 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2b870 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2b880 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2b890 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2b8a0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2b8b0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2b8c0 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2b8d0 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2b8e0 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2b8f0 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2b900 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2b910 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2b920 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2b930 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b940 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2b950 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2b960 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2b970 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2b980 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2b990 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2b9a0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2b9b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2b9c0 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2b9d0 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2b9e0 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2b9f0 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2ba00 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2ba10 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2ba20 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2ba30 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2ba40 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2ba50 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2ba60 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2ba70 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2ba80 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2ba90 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2baa0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2bab0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2bac0 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2bad0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2bae0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2baf0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2bb00 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2bb10 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2bb20 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2bb30 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2bb40 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2bb50 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2bb60 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2bb70 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2bb80 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2bb90 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2bba0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2bbb0 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2bbc0 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2bbd0 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2bbe0 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2bbf0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2bc00 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2bc10 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2bc20 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2bc30 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2bc40 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2bc50 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2bc60 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2bc70 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2bc80 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2bc90 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2bca0 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2bcb0 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2bcc0 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2bcd0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2bce0 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2bcf0 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2bd00 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2bd10 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2bd20 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2bd30 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2bd40 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2bd50 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2bd60 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2bd70 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2bd80 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2bd90 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2bda0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2bdb0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2bdc0 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2bdd0 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2bde0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2bdf0 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2be00 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2be10 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2be20 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2be30 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2be40 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2be50 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2be60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2be70 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2be80 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2be90 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2bea0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2beb0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2bec0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2bed0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2bee0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2bef0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2bf00 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2bf10 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2bf20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2bf30 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2bf40 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2bf50 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2bf60 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2bf70 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2bf80 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2bf90 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2bfa0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2bfb0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2bfc0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2bfd0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2bfe0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2bff0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2c000 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2c010 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2c020 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2c030 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2c040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c050 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2c060 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2c070 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c080 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c090 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2c0a0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2c0b0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2c0c0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2c0d0 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2c0e0 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2c0f0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2c100 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2c110 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2c120 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2c130 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2c140 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2c150 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c160 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2c170 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2c180 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2c190 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2c1a0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
2c1b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2c1c0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2c1d0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
2c1e0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2c1f0 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
2c200 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2c210 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
2c220 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2c230 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2c240 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2c250 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2c260 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2c270 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2c280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2c290 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2c2a0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2c2b0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2c2c0 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2c2d0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2c2e0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2c2f0 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2c300 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2c310 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
2c320 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2c330 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
2c340 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
2c350 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
2c360 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2c370 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
2c380 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
2c390 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2c3a0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
2c3b0 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
2c3c0 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
2c3d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2c3e0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
2c3f0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
2c400 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
2c410 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
2c420 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
2c430 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
2c440 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2c450 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
2c460 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
2c470 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
2c480 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
2c490 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
2c4a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2c4b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2c4c0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
2c4d0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c4e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2c4f0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2c500 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2c510 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
2c520 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
2c530 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
2c540 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
2c550 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
2c560 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
2c570 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
2c580 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
2c590 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2c5a0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
2c5b0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
2c5c0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
2c5d0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
2c5e0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
2c5f0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
2c600 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
2c610 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
2c620 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
2c630 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
2c640 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
2c650 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
2c660 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
2c670 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
2c680 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
2c690 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
2c6a0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
2c6b0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
2c6c0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
2c6d0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
2c6e0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
2c6f0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
2c700 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
2c710 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
2c720 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
2c730 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
2c740 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2c750 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
2c760 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
2c770 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2c780 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
2c790 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
2c7a0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
2c7b0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
2c7c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
2c7d0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
2c7e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
2c7f0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
2c800 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2c810 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
2c820 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
2c830 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
2c840 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
2c850 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2c860 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
2c870 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
2c880 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
2c890 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2c8a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2c8b0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2c8c0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2c8d0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2c8e0 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2c8f0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2c900 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2c910 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2c920 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2c930 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2c940 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2c950 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2c960 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2c970 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2c980 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c990 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2c9a0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2c9b0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2c9c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2c9d0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2c9e0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2c9f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2ca00 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2ca10 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2ca20 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2ca30 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2ca40 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2ca50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2ca60 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2ca70 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2ca80 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2ca90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2caa0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2cab0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2cac0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2cad0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2cae0 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2caf0 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2cb00 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2cb10 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2cb20 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2cb30 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2cb40 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2cb50 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2cb60 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2cb70 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2cb80 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2cb90 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2cba0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2cbb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2cbc0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2cbd0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2cbe0 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2cbf0 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2cc00 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2cc10 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2cc20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2cc30 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2cc40 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2cc50 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2cc60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2cc70 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2cc80 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2cc90 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2cca0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2ccb0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2ccc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ccd0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2cce0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2ccf0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2cd00 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2cd10 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2cd20 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2cd30 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2cd40 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2cd50 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2cd60 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2cd70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2cd80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2cd90 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2cda0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2cdb0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2cdc0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2cdd0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2cde0 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2cdf0 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2ce00 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2ce10 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2ce20 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2ce30 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2ce40 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2ce50 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2ce60 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2ce70 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2ce80 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2ce90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2cea0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2ceb0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2cec0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2ced0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2cee0 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2cef0 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2cf00 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2cf10 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2cf20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2cf30 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2cf40 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2cf50 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2cf60 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2cf70 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2cf80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2cf90 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2cfa0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2cfb0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2cfc0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2cfd0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2cfe0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2cff0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d000 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2d010 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2d020 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2d030 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2d040 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2d050 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2d060 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2d070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d080 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2d090 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2d0a0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2d0b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2d0c0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2d0d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2d0e0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2d0f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2d100 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2d110 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2d120 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2d130 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2d140 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2d150 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2d160 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d170 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2d180 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2d190 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2d1a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d1b0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2d1c0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2d1d0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2d1e0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2d1f0 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2d200 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2d210 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2d220 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2d230 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2d240 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2d250 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2d260 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2d270 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2d280 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d290 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2d2a0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2d2b0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2d2c0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2d2d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d2e0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2d2f0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2d300 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2d310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d320 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2d330 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2d340 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2d350 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2d360 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2d370 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2d380 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d390 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2d3a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2d3b0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2d3c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d3d0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2d3e0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2d3f0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2d400 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2d410 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2d420 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2d430 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2d440 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2d450 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2d460 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2d470 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2d480 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2d490 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2d4a0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2d4b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d4c0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2d4d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2d4e0 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2d4f0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2d500 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2d510 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2d520 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2d530 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2d540 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2d550 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2d560 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d570 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2d580 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2d590 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2d5a0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2d5b0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2d5c0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2d5d0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2d5e0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2d5f0 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2d600 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2d610 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2d620 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2d630 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2d640 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2d650 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d660 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2d670 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2d680 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2d690 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2d6a0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2d6b0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2d6c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2d6d0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2d6e0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2d6f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d700 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2d710 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2d720 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2d730 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2d740 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2d750 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2d760 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2d770 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2d780 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2d790 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2d7a0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2d7b0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2d7c0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2d7d0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2d7e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2d7f0 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2d800 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2d810 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2d820 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2d830 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2d840 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2d850 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2d860 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2d870 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2d880 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2d890 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2d8a0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2d8b0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2d8c0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2d8d0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2d8e0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2d8f0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2d900 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2d910 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2d920 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2d930 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2d940 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2d950 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2d960 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2d970 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2d980 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2d990 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2d9a0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2d9b0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2d9c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2d9d0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2d9e0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2d9f0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2da00 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2da10 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2da20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
2da30 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2da40 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2da50 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2da60 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
2da70 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2da80 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2da90 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2daa0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2dab0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
2dac0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
2dad0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
2dae0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2daf0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2db00 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
2db10 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2db20 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2db30 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
2db40 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
2db50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2db60 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2db70 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2db80 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2db90 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2dba0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2dbb0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2dbc0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2dbd0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2dbe0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2dbf0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
2dc00 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
2dc10 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
2dc20 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2dc30 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2dc40 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2dc50 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2dc60 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2dc70 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
2dc80 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2dc90 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
2dca0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
2dcb0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2dcc0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2dcd0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2dce0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2dcf0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2dd00 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2dd10 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2dd20 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2dd30 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2dd40 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
2dd50 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
2dd60 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
2dd70 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
2dd80 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  )^.**.** The tab
2dd90 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
2dda0 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
2ddb0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
2ddc0 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
2ddd0 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
2dde0 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
2ddf0 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
2de00 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
2de10 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
2de20 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
2de30 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
2de40 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
2de50 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
2de60 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
2de70 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
2de80 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
2de90 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
2dea0 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
2deb0 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
2dec0 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
2ded0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
2dee0 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
2def0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
2df00 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
2df10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2df20 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
2df30 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
2df40 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2df50 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
2df60 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2df70 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
2df80 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
2df90 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
2dfa0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
2dfb0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
2dfc0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2dfd0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2dfe0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
2dff0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
2e000 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2e010 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2e020 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e030 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
2e040 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
2e050 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
2e060 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
2e070 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
2e080 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2e090 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2e0a0 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
2e0b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e0c0 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
2e0d0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2e0e0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2e0f0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2e100 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2e110 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2e120 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
2e130 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2e140 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2e150 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
2e160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e170 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
2e180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e190 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
2e1a0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2e1b0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2e1c0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
2e1d0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
2e1e0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
2e1f0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
2e200 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
2e210 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
2e220 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
2e230 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
2e240 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
2e250 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
2e260 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
2e270 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
2e280 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
2e290 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
2e2a0 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
2e2b0 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
2e2c0 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
2e2d0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
2e2e0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
2e2f0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
2e300 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
2e310 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
2e320 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
2e330 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
2e340 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
2e350 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
2e360 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
2e370 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
2e380 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
2e390 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
2e3a0 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
2e3b0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
2e3c0 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
2e3d0 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
2e3e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e3f0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2e400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e410 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2e420 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2e430 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
2e440 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2e450 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2e460 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2e470 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2e480 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2e490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e4a0 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
2e4b0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
2e4c0 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
2e4d0 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
2e4e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
2e4f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2e500 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
2e510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e520 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
2e530 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
2e540 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
2e550 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
2e560 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2e570 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2e580 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2e590 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
2e5a0 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
2e5b0 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
2e5c0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
2e5d0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
2e5e0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
2e5f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e600 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
2e610 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2e620 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
2e630 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
2e640 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2e650 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
2e660 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
2e670 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e680 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
2e690 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2e6a0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
2e6b0 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
2e6c0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
2e6d0 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
2e6e0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
2e6f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2e700 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2e710 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2e720 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
2e730 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
2e740 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
2e750 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
2e760 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
2e770 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
2e780 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
2e790 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
2e7a0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2e7b0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2e7c0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
2e7d0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
2e7e0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
2e7f0 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
2e800 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2e810 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
2e820 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2e830 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
2e840 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
2e850 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
2e860 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
2e870 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
2e880 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
2e890 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
2e8a0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
2e8b0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
2e8c0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
2e8d0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
2e8e0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
2e8f0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
2e900 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2e910 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
2e920 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2e930 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
2e940 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2e950 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
2e960 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e970 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2e980 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
2e990 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e9a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2e9b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
2e9c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e9d0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
2e9e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2e9f0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2ea00 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ea10 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2ea20 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
2ea30 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2ea40 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2ea50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2ea60 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2ea70 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2ea80 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2ea90 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2eaa0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
2eab0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2eac0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2ead0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2eae0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2eaf0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2eb00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2eb10 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2eb20 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2eb30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
2eb40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2eb50 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2eb60 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
2eb70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2eb80 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
2eb90 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2eba0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2ebb0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2ebc0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2ebd0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
2ebe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ebf0 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
2ec00 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
2ec10 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
2ec20 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
2ec30 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
2ec40 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
2ec50 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
2ec60 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
2ec70 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
2ec80 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
2ec90 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
2eca0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2ecb0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
2ecc0 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
2ecd0 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
2ece0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2ecf0 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
2ed00 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2ed10 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
2ed20 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
2ed30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ed40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2ed50 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
2ed60 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
2ed70 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
2ed80 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
2ed90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2eda0 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
2edb0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
2edc0 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
2edd0 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
2ede0 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
2edf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2ee00 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
2ee10 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
2ee20 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
2ee30 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
2ee40 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
2ee50 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
2ee60 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
2ee70 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
2ee80 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2ee90 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
2eea0 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
2eeb0 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
2eec0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2eed0 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
2eee0 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
2eef0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
2ef00 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
2ef10 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
2ef20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
2ef30 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
2ef40 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
2ef50 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
2ef60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ef70 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2ef80 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
2ef90 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
2efa0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2efb0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2efc0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
2efd0 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
2efe0 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
2eff0 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
2f000 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
2f010 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
2f020 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  ruption..*/.int 
2f030 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f040 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2f050 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2f060 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
2f070 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2f080 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2f090 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
2f0a0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
2f0b0 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
2f0c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2f0d0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2f0e0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2f0f0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
2f100 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
2f110 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
2f120 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2f130 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2f140 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2f150 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2f160 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2f170 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2f180 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2f190 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2f1a0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2f1b0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2f1c0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2f1d0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
2f1e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2f1f0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2f200 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
2f210 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f220 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
2f230 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
2f240 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
2f250 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2f260 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2f270 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2f280 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2f290 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f2a0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
2f2b0 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
2f2c0 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
2f2d0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
2f2e0 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
2f2f0 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
2f300 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
2f310 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2f320 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2f330 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
2f340 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2f350 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2f360 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2f370 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2f380 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2f390 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2f3a0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
2f3b0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2f3c0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
2f3d0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2f3e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2f3f0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2f400 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
2f410 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
2f420 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
2f430 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2f440 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
2f450 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2f460 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
2f470 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
2f480 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2f490 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2f4a0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
2f4b0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
2f4c0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
2f4d0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
2f4e0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2f4f0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2f500 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f510 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2f520 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2f530 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f540 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2f550 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
2f560 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2f570 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2f580 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2f590 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2f5a0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
2f5b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2f5c0 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
2f5d0 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
2f5e0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
2f5f0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2f600 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2f610 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
2f620 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
2f630 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
2f640 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
2f650 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
2f660 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
2f670 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2f680 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
2f690 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
2f6a0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
2f6b0 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
2f6c0 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
2f6d0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2f6e0 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
2f6f0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2f700 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2f710 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2f720 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
2f730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
2f740 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
2f750 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
2f760 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
2f770 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2f780 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
2f790 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
2f7a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
2f7b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f7c0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2f7d0 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
2f7e0 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
2f7f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
2f800 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
2f810 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2f820 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2f830 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
2f840 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
2f850 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
2f860 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
2f870 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
2f880 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
2f890 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
2f8a0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
2f8b0 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
2f8c0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
2f8d0 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
2f8e0 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
2f8f0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
2f900 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
2f910 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
2f920 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
2f930 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
2f940 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
2f950 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
2f960 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
2f970 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
2f980 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
2f990 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2f9a0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
2f9b0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
2f9c0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2f9d0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
2f9e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f9f0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2fa00 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
2fa10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
2fa20 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
2fa30 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2fa40 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
2fa50 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
2fa60 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
2fa70 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
2fa80 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
2fa90 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2faa0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2fab0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
2fac0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
2fad0 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
2fae0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2faf0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
2fb00 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
2fb10 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2fb20 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
2fb30 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
2fb40 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
2fb50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2fb60 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
2fb70 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
2fb80 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
2fb90 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
2fba0 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75  s.  Every SQL fu
2fbb0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2fbc0 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62  ation must be ab
2fbd0 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  le to work.** wi
2fbe0 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
2fbf0 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
2fc00 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
2fc10 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
2fc20 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
2fc30 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
2fc40 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
2fc50 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61  er.  ^An applica
2fc60 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f  tion may.** invo
2fc70 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2fc80 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
2fc90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fca0 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
2fcb0 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
2fcc0 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
2fcd0 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
2fce0 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
2fcf0 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e  f eTextRep..** ^
2fd00 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2fd10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2fd20 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2fd30 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2fd40 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2fd50 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2fd60 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2fd70 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2fd80 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2fd90 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2fda0 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2fdb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2fdc0 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2fdd0 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2fde0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2fdf0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2fe00 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2fe10 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2fe20 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
2fe30 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2fe40 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2fe50 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2fe60 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2fe70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2fe80 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2fe90 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2fea0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2feb0 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
2fec0 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
2fed0 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
2fee0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
2fef0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
2ff00 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
2ff10 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
2ff20 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
2ff30 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2ff40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2ff50 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
2ff60 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
2ff70 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2ff80 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2ff90 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
2ffa0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
2ffb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
2ffc0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2ffd0 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
2ffe0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
2fff0 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
30000 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
30010 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
30020 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
30030 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
30040 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
30050 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
30060 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
30070 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
30080 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
30090 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
300a0 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
300b0 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
300c0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
300d0 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
300e0 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
300f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
30100 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30110 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
30120 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
30130 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
30140 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
30150 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
30160 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
30170 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
30180 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
30190 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
301a0 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
301b0 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
301c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
301d0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
301e0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
301f0 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
30200 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
30210 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
30220 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30230 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
30240 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
30250 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
30260 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
30270 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
30280 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
30290 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
302a0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
302b0 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
302c0 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
302d0 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
302e0 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
302f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
30300 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
30310 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
30320 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
30330 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
30340 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30350 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
30360 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
30370 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
30380 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
30390 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
303a0 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
303b0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
303c0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
303d0 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
303e0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
303f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
30400 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
30410 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
30420 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
30430 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
30440 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
30450 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
30460 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
30470 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
30480 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
30490 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
304a0 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
304b0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
304c0 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
304d0 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
304e0 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
304f0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
30500 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
30510 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
30520 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
30530 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
30540 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
30550 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
30560 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
30570 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
30580 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
30590 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
305a0 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
305b0 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
305c0 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
305d0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
305e0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
305f0 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
30600 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
30610 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
30620 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
30630 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
30640 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
30650 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30660 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
30670 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
30680 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30690 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
306a0 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
306b0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
306c0 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
306d0 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
306e0 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
306f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30700 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
30710 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
30720 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
30730 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
30740 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
30750 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  g..*/.int sqlite
30760 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30770 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
30780 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
30790 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
307a0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
307b0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
307c0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
307d0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
307e0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
307f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
30800 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
30810 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30820 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
30830 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
30840 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
30850 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
30860 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30870 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
30880 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
30890 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
308a0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
308b0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
308c0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
308d0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
308e0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
308f0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
30900 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
30910 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
30920 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
30930 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
30940 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
30950 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30960 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
30970 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30980 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
30990 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
309a0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
309b0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
309c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
309d0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
309e0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
309f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
30a00 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
30a10 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
30a20 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
30a30 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
30a40 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
30a50 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
30a60 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
30a70 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
30a80 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
30a90 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
30aa0 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
30ab0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
30ac0 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
30ad0 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
30ae0 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
30af0 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
30b00 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
30b10 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
30b20 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
30b30 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
30b40 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
30b50 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
30b60 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
30b70 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
30b80 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
30b90 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
30ba0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
30bb0 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
30bc0 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
30bd0 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
30be0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30bf0 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
30c00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
30c10 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
30c20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
30c30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
30c40 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
30c50 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
30c60 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
30c70 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
30c80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
30c90 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
30ca0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
30cb0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
30cc0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
30cd0 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
30ce0 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
30cf0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
30d00 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
30d10 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
30d20 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
30d30 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
30d40 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
30d50 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
30d60 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
30d70 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
30d80 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
30d90 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
30da0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
30db0 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
30dc0 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
30dd0 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
30de0 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
30df0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
30e00 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
30e10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30e20 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
30e30 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
30e40 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
30e50 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
30e60 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
30e70 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
30e80 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
30e90 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
30ea0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
30eb0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
30ec0 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
30ed0 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
30ee0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
30ef0 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
30f00 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
30f10 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
30f20 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
30f30 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
30f40 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
30f50 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20  3_int64,int),.  
30f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30f70 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65      void*,sqlite
30f80 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
30f90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30fa0 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
30fb0 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
30fc0 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
30fd0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
30fe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
30ff0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
31000 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
31010 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
31020 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
31030 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
31040 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
31050 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
31060 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
31070 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
31080 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
31090 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
310a0 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
310b0 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
310c0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
310d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
310e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
310f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
31100 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
31110 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
31120 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
31130 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
31140 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
31150 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
31160 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
31170 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
31180 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
31190 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
311a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
311b0 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
311c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
311d0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
311e0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
311f0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
31200 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
31210 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
31220 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
31230 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
31240 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
31250 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
31260 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
31270 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
31280 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31290 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
312a0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
312b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
312c0 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
312d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
312e0 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
312f0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
31300 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
31310 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
31320 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
31330 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
31340 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
31350 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
31360 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
31370 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
31380 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
31390 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
313a0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
313b0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
313c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
313d0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
313e0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
313f0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
31400 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
31410 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
31420 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
31430 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
31440 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
31450 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
31460 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
31470 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
31480 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
31490 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
314a0 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
314b0 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
314c0 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
314d0 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
314e0 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
314f0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
31500 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
31510 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
31520 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
31530 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
31540 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
31550 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
31560 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
31570 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
31580 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
31590 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
315a0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
315b0 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
315c0 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
315d0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
315e0 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
315f0 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
31600 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
31610 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
31620 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
31630 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
31640 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
31650 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
31660 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
31670 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
31680 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
31690 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
316a0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
316b0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
316c0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
316d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
316e0 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
316f0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
31700 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
31710 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
31720 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
31730 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
31740 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
31750 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
31760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31770 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
31780 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
31790 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
317a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
317b0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
317c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
317d0 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
317e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
317f0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
31800 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
31810 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
31820 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
31830 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
31840 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
31850 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
31860 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
31870 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
31880 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
31890 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
318a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
318b0 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
318c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
318d0 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
318e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
318f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
31900 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
31910 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
31920 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
31930 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
31940 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
31950 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
31960 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
31970 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
31980 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
31990 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
319a0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
319b0 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
319c0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
319d0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
319e0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
319f0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
31a00 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
31a10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
31a20 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
31a30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
31a40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31a50 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
31a60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31a70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
31a80 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
31a90 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
31aa0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
31ab0 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
31ac0 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
31ad0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
31ae0 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
31af0 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
31b00 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
31b10 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
31b20 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
31b30 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
31b40 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
31b50 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
31b60 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
31b70 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
31b80 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
31b90 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31ba0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
31bb0 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
31bc0 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
31bd0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
31be0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
31bf0 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
31c00 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
31c10 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
31c20 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
31c30 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
31c40 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
31c50 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
31c60 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
31c70 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31c80 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
31c90 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
31ca0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
31cb0 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
31cc0 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
31cd0 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
31ce0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
31cf0 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
31d00 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
31d10 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
31d20 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
31d30 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
31d40 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
31d50 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
31d60 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
31d70 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
31d80 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
31d90 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
31da0 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
31db0 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
31dc0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
31dd0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
31de0 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
31df0 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
31e00 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
31e10 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
31e20 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
31e30 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31e40 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
31e50 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
31e60 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
31e70 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
31e80 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
31e90 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31ea0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
31eb0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
31ec0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20  ULL pointer .** 
31ed0 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65  when first calle
31ee0 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  d if N is less t
31ef0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
31f00 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
31f10 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20  ory.** allocate 
31f20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
31f30 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
31f40 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
31f50 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
31f60 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31f70 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
31f80 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
31f90 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
31fa0 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
31fb0 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
31fc0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
31fd0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
31fe0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
31ff0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32000 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
32010 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
32020 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
32030 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
32040 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
32050 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69  llocation.)^  Wi
32060 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  thin the xFinal 
32070 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20  callback, it is 
32080 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74  customary to set
32090 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73  .** N=0 in calls
320a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to 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 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a  N) so that no .*
320d0 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f  * pointless memo
320e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f  ry allocations o
320f0 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ccur..**.** ^SQL
32100 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
32110 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
32120 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
32130 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
32140 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
32150 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
32160 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
32170 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
32180 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
32190 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
321a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
321b0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
321c0 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
321d0 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
321e0 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
321f0 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
32200 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
32210 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
32220 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
32230 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
32240 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
32250 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
32260 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
32270 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
32280 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
32290 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
322a0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
322b0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
322c0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
322d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
322e0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
322f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
32300 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
32310 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
32320 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
32330 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
32340 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
32350 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
32360 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
32370 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
32380 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
32390 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
323a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
323b0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
323c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
323d0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
323e0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
323f0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
32400 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
32410 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32420 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
32430 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
32440 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
32450 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
32460 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
32470 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32480 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
32490 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
324a0 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
324b0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
324c0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
324d0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
324e0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
324f0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
32500 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
32510 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
32520 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
32530 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
32540 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
32550 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
32560 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
32570 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
32580 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
32590 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
325a0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
325b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
325c0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
325d0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
325e0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
325f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32600 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32610 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
32620 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
32630 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
32640 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
32650 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
32660 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
32670 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ata.**.** These 
32680 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
32690 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67   used by (non-ag
326a0 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e  gregate) SQL fun
326b0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
326c0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
326d0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
326e0 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
326f0 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
32700 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
32710 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
32720 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
32730 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
32740 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
32750 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
32760 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
32770 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
32780 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
32790 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a  ed.  An example.
327a0 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73  ** of where this
327b0 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c   might be useful
327c0 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72   is in a regular
327d0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
327e0 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  hing.** function
327f0 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
32800 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
32810 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
32820 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61   can be stored a
32830 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
32840 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
32850 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
32860 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c  .  .** Then as l
32870 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65  ong as the patte
32880 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e  rn string remain
32890 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74  s the same,.** t
328a0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
328b0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
328c0 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
328d0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
328e0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
328f0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ame function..**
32900 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32910 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
32920 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32930 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
32940 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
32950 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
32960 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32970 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
32980 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
32990 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
329a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
329b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
329c0 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  n. ^If there is 
329d0 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  no metadata.** a
329e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
329f0 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  he function argu
32a00 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74  ment, this sqlit
32a10 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
32a20 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
32a30 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
32a40 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
32a50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
32a60 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e  data(C,N,P,X) in
32a70 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20  terface saves P 
32a80 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  as metadata for 
32a90 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
32aa0 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
32ab0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32ac0 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73  function.  ^Subs
32ad0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
32ae0 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
32af0 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75  uxdata(C,N) retu
32b00 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rn P from the mo
32b10 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c  st recent.** sql
32b20 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32b30 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69  (C,N,P,X) call i
32b40 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  f the metadata i
32b50 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72  s still valid or
32b60 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20  .** NULL if the 
32b70 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
32b80 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  n discarded..** 
32b90 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c  ^After each call
32ba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
32bb0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
32bc0 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20   where X is not 
32bd0 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  NULL,.** SQLite 
32be0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
32bf0 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
32c00 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d  ion X with param
32c10 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a  eter P exactly.*
32c20 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65  * once, when the
32c30 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73   metadata is dis
32c40 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74  carded..** SQLit
32c50 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73  e is free to dis
32c60 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74  card the metadat
32c70 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69  a at any time, i
32c80 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a  ncluding: <ul>.*
32c90 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20  * <li> when the 
32ca0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
32cb0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
32cc0 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20   changes, or.** 
32cd0 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74  <li> when [sqlit
32ce0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
32cf0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
32d00 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ()] is called fo
32d10 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51  r the.**      SQ
32d20 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a  L statement, or.
32d30 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c  ** <li> when sql
32d40 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32d50 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67  () is invoked ag
32d60 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ain on the same 
32d70 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a  parameter, or.**
32d80 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65   <li> during the
32d90 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65   original sqlite
32da0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
32db0 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f  call when a memo
32dc0 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f  ry .**      allo
32dd0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
32de0 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  urs. </ul>)^.**.
32df0 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74  ** Note the last
32e00 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69   bullet in parti
32e10 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74  cular.  The dest
32e20 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20  ructor X in .** 
32e30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32e40 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67  ata(C,N,P,X) mig
32e50 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d  ht be called imm
32e60 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
32e70 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
32e80 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
32e90 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74  terface even ret
32ea0 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c  urns.  Hence sql
32eb0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32ec0 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  ().** should be 
32ed0 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20  called near the 
32ee0 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74  end of the funct
32ef0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
32f00 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75  on and the.** fu
32f10 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
32f20 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
32f30 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66   make any use of
32f40 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69   P after.** sqli
32f50 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32f60 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ) has been calle
32f70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
32f80 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
32f90 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
32fa0 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
32fb0 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63  alls for.** func
32fc0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tion parameters 
32fd0 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65  that are compile
32fe0 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c  -time constants,
32ff0 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72   including liter
33000 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
33010 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e   [parameters] an
33020 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  d expressions co
33030 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20  mposed from the 
33040 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  same.)^.**.** Th
33050 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
33060 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
33070 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
33080 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
33090 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
330a0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
330b0 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
330c0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
330d0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
330e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
330f0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
33100 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
33110 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
33120 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
33130 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
33140 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
33150 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
33160 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
33170 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
33180 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
33190 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
331a0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
331b0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
331c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
331d0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
331e0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
331f0 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
33200 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
33210 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
33220 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
33230 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
33240 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
33250 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
33260 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
33270 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
33280 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
33290 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
332a0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
332b0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
332c0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
332d0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
332e0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
332f0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
33300 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
33310 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
33320 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
33330 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
33340 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
33350 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
33360 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
33370 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
33380 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
33390 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70  ompilers..*/.typ
333a0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
333b0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
333c0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
333d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
333e0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
333f0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
33400 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
33410 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
33420 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
33430 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
33440 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
33450 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
33460 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
33470 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
33480 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
33490 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
334a0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
334b0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
334c0 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
334d0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
334e0 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
334f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33500 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
33510 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33520 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
33530 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
33540 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
33550 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
33560 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
33570 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
33580 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
33590 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
335a0 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
335b0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
335c0 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
335d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
335e0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
335f0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
33600 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
33610 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
33620 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
33630 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33640 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
33650 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
33660 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
33670 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33680 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33690 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
336a0 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
336b0 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
336c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
336d0 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
336e0 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
336f0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
33700 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
33710 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33720 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
33730 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
33740 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
33750 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
33760 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33770 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
33780 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
33790 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
337a0 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
337b0 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
337c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
337d0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
337e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
337f0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
33800 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
33810 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
33820 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
33830 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33840 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
33850 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
33860 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
33870 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
33880 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
33890 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
338a0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
338b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
338c0 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
338d0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
338e0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
338f0 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
33900 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
33910 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
33920 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
33930 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
33940 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
33950 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33960 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
33970 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
33980 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
33990 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
339a0 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
339b0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
339c0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
339d0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
339e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
339f0 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
33a00 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
33a10 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
33a20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33a30 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
33a40 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
33a50 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
33a60 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
33a70 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
33a80 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
33a90 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
33aa0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
33ab0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
33ac0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
33ad0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
33ae0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
33af0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
33b00 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
33b10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
33b20 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
33b30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33b40 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
33b50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33b60 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
33b70 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
33b80 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
33b90 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
33ba0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
33bb0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
33bc0 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
33bd0 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
33be0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33bf0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
33c00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33c10 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
33c20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
33c30 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
33c40 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
33c50 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
33c60 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
33c70 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
33c80 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
33c90 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
33ca0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
33cb0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
33cc0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
33cd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33ce0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
33cf0 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
33d00 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
33d10 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
33d20 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
33d30 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
33d40 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
33d50 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
33d60 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
33d70 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
33d80 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
33d90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33da0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
33db0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33dc0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
33dd0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
33de0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
33df0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33e00 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
33e10 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
33e20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
33e30 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
33e40 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
33e50 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
33e60 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
33e70 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
33e80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33e90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
33ea0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
33eb0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
33ec0 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
33ed0 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
33ee0 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
33ef0 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
33f00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33f10 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
33f20 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
33f30 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
33f40 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
33f50 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33f60 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
33f70 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
33f80 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
33f90 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
33fa0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
33fb0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33fc0 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
33fd0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
33fe0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
33ff0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34000 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34010 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
34020 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
34030 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
34040 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
34050 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
34060 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
34070 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
34080 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
34090 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
340a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
340b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
340c0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
340d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
340e0 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
340f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
34100 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
34110 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
34120 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
34130 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
34140 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
34150 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
34160 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
34170 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34180 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
34190 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
341a0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
341b0 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
341c0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
341d0 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
341e0 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
341f0 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
34200 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
34210 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  y..** ^SQLite ta
34220 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
34230 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
34240 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
34250 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
34260 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
34270 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
34280 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
34290 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
342a0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
342b0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
342c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
342d0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
342e0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
342f0 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
34300 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
34310 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
34320 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
34330 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
34340 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
34350 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
34360 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
34370 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
34380 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
34390 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
343a0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
343b0 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
343c0 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
343d0 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
343e0 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
343f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34400 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
34410 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64  ult.  If the 3rd
34420 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
34430 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
34440 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74   it.** must be t
34450 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69  he byte offset i
34460 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77  nto the string w
34470 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
34480 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a  minator would.**
34490 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73   appear if the s
344a0 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20  tring where NUL 
344b0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
344c0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
344d0 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  rs occur.** in t
344e0 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62  he string at a b
344f0 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20  yte offset that 
34500 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  is less than the
34510 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72   value of the 3r
34520 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20  d.** parameter, 
34530 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
34540 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63  ng string will c
34550 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
34560 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  NULs and the.** 
34570 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
34580 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20  sions operating 
34590 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20  on strings with 
345a0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
345b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
345c0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
345d0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
345e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
345f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
34600 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34610 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
34620 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
34630 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
34640 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
34650 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
34660 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
34670 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
34680 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
34690 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
346a0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
346b0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
346c0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
346d0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
346e0 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
346f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34700 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
34710 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
34720 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
34730 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
34740 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
34750 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
34760 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
34770 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
34780 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
34790 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
347a0 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
347b0 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
347c0 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
347d0 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
347e0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
347f0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
34800 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
34810 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
34820 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
34830 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
34840 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
34850 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
34860 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
34870 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
34880 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
34890 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
348a0 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
348b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
348c0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
348d0 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
348e0 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
348f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34900 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
34910 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34920 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
34930 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34940 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34950 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
34960 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
34970 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34980 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
34990 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
349a0 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
349b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
349c0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
349d0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
349e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
349f0 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
34a00 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34a10 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
34a20 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
34a30 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
34a40 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
34a50 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
34a60 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
34a70 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
34a80 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
34a90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34aa0 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
34ab0 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
34ac0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
34ad0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
34ae0 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
34af0 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
34b00 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
34b10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34b20 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
34b30 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
34b40 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
34b50 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
34b60 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
34b70 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
34b80 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
34b90 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
34ba0 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
34bb0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34bc0 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
34bd0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
34be0 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
34bf0 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
34c00 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
34c10 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34c20 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
34c30 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34c40 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
34c50 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
34c60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34c70 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
34c80 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
34c90 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
34ca0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
34cb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34cc0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
34cd0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
34ce0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
34cf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34d00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
34d10 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
34d20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
34d30 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
34d40 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
34d50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34d60 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
34d70 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
34d80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34d90 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
34da0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
34db0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34dc0 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
34dd0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
34de0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34df0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
34e00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
34e10 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
34e20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34e30 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
34e40 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
34e50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34e60 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
34e70 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
34e80 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
34e90 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
34ea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34eb0 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
34ec0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
34ed0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
34ee0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
34ef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34f00 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
34f10 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
34f20 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
34f30 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
34f40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34f50 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
34f60 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
34f70 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
34f80 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
34f90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34fa0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
34fb0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
34fc0 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
34fd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
34fe0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
34ff0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
35000 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35010 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
35020 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
35030 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
35040 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76  tions add, remov
35050 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b  e, or modify a [
35060 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63  collation] assoc
35070 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
35080 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35090 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
350a0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
350b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
350c0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
350d0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55  collation is a U
350e0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
350f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
35100 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
35110 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
35120 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
35130 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
35140 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
35150 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
35160 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35170 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
35180 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65   ^Collation name
35190 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65  s that compare e
351a0 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74  qual according t
351b0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69  o [sqlite3_strni
351c0 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f  cmp()] are.** co
351d0 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74  nsidered to be t
351e0 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
351f0 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20  .** ^(The third 
35200 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52  argument (eTextR
35210 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  ep) must be one 
35220 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
35230 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
35240 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  > [SQLITE_UTF8],
35250 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
35260 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16LE],.** <l
35270 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
35280 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BE],.** <li> [SQ
35290 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a  LITE_UTF16], or.
352a0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
352b0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a  UTF16_ALIGNED]..
352c0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54  ** </ul>)^.** ^T
352d0 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
352e0 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20  ment determines 
352f0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
35300 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a  strings passed.*
35310 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  * to the collati
35320 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
35330 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e  back, xCallback.
35340 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
35350 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c  _UTF16] and [SQL
35360 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
35370 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54  D] values for eT
35380 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20  extRep.** force 
35390 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54  strings to be UT
353a0 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20  F16 with native 
353b0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
353c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
353d0 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
353e0 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f   for eTextRep fo
353f0 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20  rces strings to 
35400 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65  begin.** on an e
35410 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73  ven byte address
35420 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
35430 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41  rth argument, pA
35440 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63  rg, is an applic
35450 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
35460 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
35470 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20  d.** through as 
35480 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
35490 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  nt to the collat
354a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
354b0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
354c0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
354d0 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20  , xCallback, is 
354e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
354f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35500 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c  ion..** ^Multipl
35510 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35520 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67  tions can be reg
35530 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
35540 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a  e same name but.
35550 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ** with differen
35560 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d  t eTextRep param
35570 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65  eters and SQLite
35580 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65   will use whiche
35590 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ver.** function 
355a0 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
355b0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
355c0 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  a transformation
355d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61  ..** ^If the xCa
355e0 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
355f0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
35600 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35610 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65  ion is.** delete
35620 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f  d.  ^When all co
35630 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35640 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d  s having the sam
35650 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74  e name are delet
35660 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c  ed,.** that coll
35670 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ation is no long
35680 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  er usable..**.**
35690 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20   ^The collating 
356a0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
356b0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
356c0 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  h a copy of the 
356d0 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61  pArg .** applica
356e0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
356f0 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73  r and with two s
35700 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e  trings in the en
35710 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
35720 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74  .** by the eText
35730 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Rep argument.  T
35740 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
35750 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72  ction must retur
35760 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  n an.** integer 
35770 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65  that is negative
35780 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74  , zero, or posit
35790 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69  ive.** if the fi
357a0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
357b0 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74  ss than, equal t
357c0 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
357d0 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a  an the second,.*
357e0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
357f0 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
35800 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79  ction must alway
35810 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
35820 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65  e answer.** give
35830 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  n the same input
35840 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  s.  If two or mo
35850 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  re collating fun
35860 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73  ctions are regis
35870 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  tered.** to the 
35880 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e  same collation n
35890 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65  ame (using diffe
358a0 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61  rent eTextRep va
358b0 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a  lues) then all.*
358c0 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65  * must give an e
358d0 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72  quivalent answer
358e0 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69   when invoked wi
358f0 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74  th equivalent st
35900 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f  rings..** The co
35910 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35920 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66   must obey the f
35930 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74  ollowing propert
35940 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73  ies for all.** s
35950 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64  trings A, B, and
35960 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   C:.**.** <ol>.*
35970 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74  * <li> If A==B t
35980 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69  hen B==A..** <li
35990 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d  > If A==B and B=
359a0 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a  =C then A==C..**
359b0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
359c0 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20  THEN B&gt;A..** 
359d0 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61  <li> If A&lt;B a
359e0 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41  nd B&lt;C then A
359f0 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  &lt;C..** </ol>.
35a00 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61  **.** If a colla
35a10 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61  ting function fa
35a20 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61  ils any of the a
35a30 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  bove constraints
35a40 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c   and that.** col
35a50 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35a60 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61  is  registered a
35a70 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  nd used, then th
35a80 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  e behavior of SQ
35a90 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  Lite.** is undef
35aa0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
35ab0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35ac0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
35ad0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
35ae0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35af0 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65  on().** with the
35b00 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74   addition that t
35b10 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
35b20 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
35b30 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20  on pArg when.** 
35b40 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
35b50 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
35b60 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67  d..** ^Collating
35b70 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64   functions are d
35b80 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79  eleted when they
35b90 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
35ba0 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c  by later.** call
35bb0 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  s to the collati
35bc0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
35bd0 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
35be0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
35bf0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
35c00 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  osed using [sqli
35c10 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
35c20 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f  .** ^The xDestro
35c30 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75  y callback is <u
35c40 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20  >not</u> called 
35c50 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74  if the .** sqlit
35c60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35c70 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f  ion_v2() functio
35c80 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63  n fails.  Applic
35c90 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f  ations that invo
35ca0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  ke.** sqlite3_cr
35cb0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
35cc0 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  2() with a non-N
35cd0 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67  ULL xDestroy arg
35ce0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  ument should .**
35cf0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
35d00 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f  n code and dispo
35d10 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  se of the applic
35d20 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
35d30 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73  er.** themselves
35d40 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70   rather than exp
35d50 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f  ecting SQLite to
35d60 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f   deal with it fo
35d70 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20  r them..** This 
35d80 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  is different fro
35d90 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51  m every other SQ
35da0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
35db0 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e   The inconsisten
35dc0 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74  cy .** is unfort
35dd0 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74  unate but cannot
35de0 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68   be changed with
35df0 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63  out breaking bac
35e00 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61  kwards .** compa
35e10 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
35e20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69  See also:  [sqli
35e30 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
35e40 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  eded()] and [sql
35e50 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
35e60 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69  eeded16()]..*/.i
35e70 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
35e80 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
35e90 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
35ea0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
35eb0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
35ec0 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
35ed0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
35ee0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
35ef0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
35f00 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
35f10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35f20 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
35f30 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
35f40 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
35f50 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
35f60 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
35f70 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
35f80 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
35f90 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
35fa0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
35fb0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
35fc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
35fd0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
35fe0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
35ff0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
36000 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
36010 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
36020 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
36030 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
36040 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
36050 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
36060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
36070 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
36080 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
36090 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67  ^To avoid having
360a0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
360b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
360c0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
360d0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
360e0 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
360f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
36100 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
36110 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
36120 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36130 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f  tion] to be invo
36140 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
36150 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
36160 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
36170 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
36180 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  ** ^If the funct
36190 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
361a0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
361b0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
361c0 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
361d0 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
361e0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
361f0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
36200 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
36210 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
36220 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20  d in UTF-8. ^If 
36230 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
36240 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
36250 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
36260 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
36270 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
36280 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
36290 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  rder..** ^A call
362a0 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
362b0 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65  ion replaces the
362c0 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74   existing collat
362d0 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62  ion-needed callb
362e0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65  ack..**.** ^(Whe
362f0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
36300 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
36310 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
36320 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
36330 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
36340 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
36350 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
36360 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
36370 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36380 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
36390 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
363a0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
363b0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
363c0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
363d0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
363e0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
363f0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
36400 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
36410 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
36420 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
36430 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
36440 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
36450 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
36460 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
36470 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
36480 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
36490 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
364a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
364b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  .)^.**.** The ca
364c0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
364d0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
364e0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
364f0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
36500 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36510 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
36520 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36530 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
36540 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
36550 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
36560 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
36570 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
36580 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
36590 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
365a0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
365b0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
365c0 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
365d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
365e0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
365f0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
36600 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
36610 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
36620 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
36630 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
36640 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
36650 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
36660 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
36670 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
36680 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
36690 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
366a0 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
366b0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
366c0 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
366d0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
366e0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
366f0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
36700 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
36710 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
36720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  */.int sqlite3_k
36730 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
36740 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
36750 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
36760 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
36770 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
36780 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
36790 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
367a0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
367b0 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  key_v2(.  sqlite
367c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
367d0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
367e0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
367f0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  ed */.  const ch
36800 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
36810 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
36820 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a  f the database *
36830 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
36840 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
36850 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
36860 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
36870 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
36880 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
36890 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
368a0 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
368b0 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
368c0 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
368d0 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
368e0 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
368f0 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
36900 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
36910 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
36920 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
36930 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
36940 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
36950 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
36960 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
36970 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
36980 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
369a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
369b0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
369c0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
369d0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
369e0 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
369f0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
36a00 5f 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c  _rekey_v2(.  sql
36a10 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
36a20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
36a30 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
36a40 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
36a50 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
36a60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d            /* Nam
36a70 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
36a80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
36a90 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
36aa0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
36ab0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
36ac0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
36ad0 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
36ae0 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
36af0 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
36b00 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
36b10 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
36b20 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
36b30 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
36b40 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73  vate_see(.  cons
36b50 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
36b60 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
36b70 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
36b80 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69  */.);.#endif..#i
36b90 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42  fdef SQLITE_ENAB
36ba0 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53  LE_CEROD./*.** S
36bb0 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
36bc0 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
36bd0 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20  CEROD database. 
36be0 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
36bf0 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
36c00 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65  he CEROD routine
36c10 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
36c20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
36c30 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63  ivate_cerod(.  c
36c40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
36c50 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
36c60 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
36c70 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
36c80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36c90 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
36ca0 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
36cb0 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ime.**.** The sq
36cc0 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
36cd0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
36ce0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
36cf0 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
36d00 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
36d10 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
36d20 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
36d30 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
36d40 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
36d50 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
36d60 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
36d70 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
36d80 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
36d90 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
36da0 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
36db0 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
36dc0 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
36dd0 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
36de0 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
36df0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
36e00 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
36e10 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
36e20 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
36e30 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
36e40 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
36e50 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
36e60 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
36e70 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
36e80 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
36e90 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
36ea0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
36eb0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65   object.  If the
36ec0 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
36ed0 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75  .** of the defau
36ee0 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d  lt VFS is not im
36ef0 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63  plemented correc
36f00 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c  tly, or not impl
36f10 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c  emented at.** al
36f20 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  l, then the beha
36f30 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
36f40 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69  sleep() may devi
36f50 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73  ate from the des
36f60 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74  cription.** in t
36f70 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
36f80 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73  graphs..*/.int s
36f90 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
36fa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36fb0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
36fc0 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
36fd0 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
36fe0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
36ff0 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
37000 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
37010 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
37020 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
37030 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
37040 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
37050 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
37060 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
37070 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
37080 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
37090 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  t-in [sqlite3_vf
370a0 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c  s | VFS].** will
370b0 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
370c0 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
370d0 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
370e0 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
370f0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
37100 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
37110 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
37120 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
37130 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
37140 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
37150 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
37160 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
37170 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
37180 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
37190 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
371a0 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
371b0 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
371c0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
371d0 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
371e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
371f0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
37200 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
37210 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
37220 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
37230 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
37240 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
37250 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
37260 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
37270 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
37280 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
37290 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
372a0 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
372b0 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
372c0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
372d0 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
372e0 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
372f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65  ..**.** ^The [te
37300 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
37310 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
37320 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
37330 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
37340 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
37350 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
37360 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
37370 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
37380 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
37390 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
373a0 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
373b0 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
373c0 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
373d0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
373e0 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
373f0 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
37400 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
37410 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
37420 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
37430 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
37440 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
37450 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
37460 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
37470 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
37480 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
37490 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
374a0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
374b0 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
374c0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
374d0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
374e0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
374f0 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
37500 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
37510 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
37520 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
37530 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a  d be avoided..**
37540 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
37550 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
37560 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
37570 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
37580 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
37590 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
375a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
375b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
375c0 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69  en_v2].  Otherwi
375d0 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
375e0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
375f0 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
37600 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
37610 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20  may fail.  Here 
37620 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65  is an.** example
37630 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68   of how to do th
37640 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74  is using C++ wit
37650 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75  h the Windows Ru
37660 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntime:.**.** <bl
37670 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
37680 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20  * LPCWSTR zPath 
37690 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61  = Windows::Stora
376a0 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44  ge::ApplicationD
376b0 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a  ata::Current->.*
376c0 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d  * &nbsp;     Tem
376d0 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61  poraryFolder->Pa
376e0 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63  th->Data();.** c
376f0 68 61 72 20 7a 50 61 74 68 42 75 66 26 23 39 31  har zPathBuf&#91
37700 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39  ;MAX_PATH + 1&#9
37710 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50  3;;.** memset(zP
37720 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f  athBuf, 0, sizeo
37730 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a  f(zPathBuf));.**
37740 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69   WideCharToMulti
37750 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c  Byte(CP_UTF8, 0,
37760 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74   zPath, -1, zPat
37770 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61  hBuf, sizeof(zPa
37780 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70  thBuf),.** &nbsp
37790 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c  ;     NULL, NULL
377a0 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65  );.** sqlite3_te
377b0 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73  mp_directory = s
377c0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
377d0 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a  %s", zPathBuf);.
377e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
377f0 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45  quote>.*/.SQLITE
37800 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
37810 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
37820 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
37830 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
37840 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
37850 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73  g Database Files
37860 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
37870 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
37880 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
37890 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
378a0 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
378b0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
378c0 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
378d0 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61  ), then all data
378e0 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70  base files.** sp
378f0 65 63 69 66 69 65 64 20 77 69 74 68 20 61 20 72  ecified with a r
37900 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
37910 20 61 6e 64 20 63 72 65 61 74 65 64 20 6f 72 20   and created or 
37920 61 63 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 53  accessed by.** S
37930 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67  QLite when using
37940 20 61 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64   a built-in wind
37950 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ows [sqlite3_vfs
37960 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20   | VFS] will be 
37970 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65  assumed.** to be
37980 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61   relative to tha
37990 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e  t directory.)^ ^
379a0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
379b0 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   is a NULL.** po
379c0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
379d0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
379e0 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  all database fil
379f0 65 73 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  es specified.** 
37a00 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20  with a relative 
37a10 70 61 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c  pathname are rel
37a20 61 74 69 76 65 20 74 6f 20 74 68 65 20 63 75 72  ative to the cur
37a30 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a  rent directory.*
37a40 2a 20 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73  * for the proces
37a50 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e  s.  Only the win
37a60 64 6f 77 73 20 56 46 53 20 6d 61 6b 65 73 20 75  dows VFS makes u
37a70 73 65 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 61  se of this globa
37a80 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 69  l.** variable; i
37a90 74 20 69 73 20 69 67 6e 6f 72 65 64 20 62 79 20  t is ignored by 
37aa0 74 68 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a  the unix VFS..**
37ab0 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 65  .** Changing the
37ac0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 76   value of this v
37ad0 61 72 69 61 62 6c 65 20 77 68 69 6c 65 20 61 20  ariable while a 
37ae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37af0 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63  ion is.** open c
37b00 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63  an result in a c
37b10 6f 72 72 75 70 74 20 64 61 74 61 62 61 73 65 2e  orrupt database.
37b20 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
37b30 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
37b40 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
37b50 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
37b60 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
37b70 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
37b80 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
37b90 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
37ba0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
37bb0 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
37bc0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
37bd0 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
37be0 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
37bf0 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
37c00 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
37c10 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
37c20 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
37c30 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
37c40 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
37c50 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
37c60 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
37c70 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
37c80 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
37c90 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
37ca0 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
37cb0 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
37cc0 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
37cd0 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 6f  * ^The [data_sto
37ce0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
37cf0 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20  gma] may modify 
37d00 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e  this variable an
37d10 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f  d cause.** it to
37d20 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
37d30 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
37d40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e  sqlite3_malloc].
37d50 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a    ^Furthermore,.
37d60 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f  ** the [data_sto
37d70 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
37d80 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75  gma] always assu
37d90 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72  mes that any str
37da0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73  ing.** that this
37db0 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73   variable points
37dc0 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d   to is held in m
37dd0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
37de0 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
37df0 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65  _malloc] and the
37e00 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65   pragma may atte
37e10 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74  mpt to free that
37e20 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67   memory.** using
37e30 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e   [sqlite3_free].
37e40 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68  .** Hence, if th
37e50 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  is variable is m
37e60 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79  odified directly
37e70 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75  , either it shou
37e80 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55  ld be.** made NU
37e90 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f  LL or made to po
37ea0 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
37eb0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
37ec0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20  ite3_malloc].** 
37ed0 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20  or else the use 
37ee0 6f 66 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f  of the [data_sto
37ef0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
37f00 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61  gma] should be a
37f10 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  voided..*/.SQLIT
37f20 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
37f30 71 6c 69 74 65 33 5f 64 61 74 61 5f 64 69 72 65  qlite3_data_dire
37f40 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
37f50 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72  PI3REF: Test For
37f60 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
37f70 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
37f80 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d  autocommit mode}
37f90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37fa0 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
37fb0 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  it() interface r
37fc0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
37fd0 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68  or.** zero if th
37fe0 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65  e given database
37ff0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
38000 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
38010 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20  commit mode,.** 
38020 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e  respectively.  ^
38030 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
38040 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
38050 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
38060 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
38070 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
38080 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75  tatement..** ^Au
38090 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
380a0 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
380b0 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
380c0 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
380d0 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
380e0 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
380f0 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
38100 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
38110 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
38120 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
38130 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
38140 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
38150 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
38160 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
38170 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
38180 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
38190 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
381a0 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
381b0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
381c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
381d0 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
381e0 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
381f0 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
38200 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
38210 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
38220 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
38230 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
38240 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
38250 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
38260 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
38270 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
38280 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
38290 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
382a0 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
382b0 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
382c0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
382d0 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
382e0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
382f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
38300 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29  commit(sqlite3*)
38310 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38320 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61  F: Find The Data
38330 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41  base Handle Of A
38340 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
38350 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ent.**.** ^The s
38360 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
38370 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38380 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ns the [database
38390 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
383a0 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20  dle.** to which 
383b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
383c0 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20  ement] belongs. 
383d0 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20   ^The [database 
383e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72  connection].** r
383f0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
38400 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20  e3_db_handle is 
38410 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
38420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
38430 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  * that was the f
38440 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
38450 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
38460 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
38470 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
38480 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
38490 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
384a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
384b0 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
384c0 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  e..*/.sqlite3 *s
384d0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
384e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
384f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38500 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c  : Return The Fil
38510 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61  ename For A Data
38520 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
38530 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38540 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44  e3_db_filename(D
38550 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
38560 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
38570 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a  to a filename.**
38580 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
38590 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63   database N of c
385a0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54  onnection D.  ^T
385b0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
385c0 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65   file.** has the
385d0 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49   name "main".  I
385e0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74  f there is no at
385f0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 20  tached database 
38600 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  N on the databas
38610 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
38620 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61 73  D, or if databas
38630 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61  e N is a tempora
38640 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20  ry or in-memory 
38650 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a  database, then.*
38660 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
38670 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
38680 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  .** ^The filenam
38690 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
386a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  is function is t
386b0 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65  he output of the
386c0 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  .** xFullPathnam
386d0 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  e method of the 
386e0 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65  [VFS].  ^In othe
386f0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c  r words, the fil
38700 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  ename.** will be
38710 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
38720 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74  hname, even if t
38730 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64  he filename used
38740 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  .** to open the 
38750 64 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61  database origina
38760 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f 72  lly was a URI or
38770 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61   relative pathna
38780 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  me..*/.const cha
38790 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66 69  r *sqlite3_db_fi
387a0 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20 2a  lename(sqlite3 *
387b0 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  db, const char *
387c0 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a  zDbName);../*.**
387d0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
387e0 6d 69 6e 65 20 69 66 20 61 20 64 61 74 61 62 61  mine if a databa
387f0 73 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a  se is read-only.
38800 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38810 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44  e3_db_readonly(D
38820 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
38830 74 75 72 6e 73 20 31 20 69 66 20 74 68 65 20 64  turns 1 if the d
38840 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20  atabase N.** of 
38850 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73 20  connection D is 
38860 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20