/ Hex Artifact Content
Login

Artifact 7ada7e40ce547661b90230630af3bef1a862988a:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
4090: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63  t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69  rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5950: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5970: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5990: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
59a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
59b0: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
5a20: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a60: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
5ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ae0: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
5af0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b00: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
5b10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
5b30: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
5b40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
5b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b70: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
5b80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b90: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5ba0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5bb0: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
5bc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5bd0: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
5be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5bf0: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
5c00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5c10: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
5c20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
5c40: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5c50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
5c60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c70: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5c80: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
5c90: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
5ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cb0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5cc0: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
5cd0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
5ce0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cf0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
5d00: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
5d10: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
5d20: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5d30: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5d40: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5d50: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5d60: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5d70: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5d80: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5d90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5da0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5db0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5dc0: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5dd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5df0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5e00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e10: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5e20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e30: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5e40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5e50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e60: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5e70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e80: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5e90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ea0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5eb0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5ec0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5ed0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5ee0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f00: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5f10: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5f20: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
5f30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
5f50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5f60: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5f70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f80: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5f90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5fa0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5fb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fc0: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5fd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5fe0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5ff0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6010: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6020: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6030: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6040: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6050: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6060: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
6070: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6080: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
60b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
60c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60e0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
60f0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6100: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6130: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6140: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
6170: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
6180: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6190: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61a0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
61b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
61c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61e0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
61f0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6200: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6210: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6220: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6230: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6240: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6250: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
6280: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
6290: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
62b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62c0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
62d0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
62e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6300: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6310: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6320: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6330: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6340: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6350: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6360: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
6370: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
6380: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6390: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63a0: 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43  _OPEN_FILEPROTEC
63b0: 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20 20  TION_MASK       
63c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 37 30            0x0070
63e0: 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76 65  0000../* Reserve
63f0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
6400: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
6410: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
6420: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
6430: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
6440: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
6450: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6460: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
6470: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6480: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
6490: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
64a0: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
64b0: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
64c0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
64d0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
64e0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
64f0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
6500: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
6510: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
6520: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6530: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
6540: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
6550: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6560: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6570: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6580: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6590: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
65a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
65b0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
65c0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
65d0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
65e0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
65f0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
6600: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
6610: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6620: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6630: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6640: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6650: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6660: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6670: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6680: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6690: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
66a0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
66b0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
66c0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
66d0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
66e0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
66f0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
6700: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
6710: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6720: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6730: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6740: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6750: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6760: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6770: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6780: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6790: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
67a0: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
67b0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
67c0: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
67d0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
67e0: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
67f0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
6800: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
6810: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
6820: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
6830: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
6840: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6850: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6860: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6870: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6880: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6890: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
68a0: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
68b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
68c0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
68d0: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63  EN.** flag indic
68e0: 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20  ate that a file 
68f0: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6900: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6910: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6920: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6930: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6940: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6950: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6960: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6970: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6980: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6990: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
69a0: 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  leges..*/.#defin
69b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69c0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
69d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
69e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a10: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
6a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a30: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
6a40: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
6a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a60: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
6a70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a80: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6aa0: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
6ab0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ad0: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
6ae0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6af0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6b10: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
6b20: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6b60: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6b90: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6bb0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
6bc0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6be0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6bf0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c00: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6c20: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6c30: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
6c40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c50: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6c60: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
6c70: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
6c80: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
6c90: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  BLE             
6ca0: 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a   0x00002000../*.
6cb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
6cc0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
6cd0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
6ce0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
6cf0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d00: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
6d10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
6d20: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
6d30: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
6d40: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
6d50: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
6d60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6d70: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
6d80: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
6d90: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
6da0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6db0: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
6dc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6dd0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
6de0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
6df0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6e00: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
6e10: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
6e20: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
6e30: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
6e40: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
6e50: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
6e60: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
6e70: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
6e80: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6e90: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6ea0: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
6eb0: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
6ec0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
6ed0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6ee0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
6ef0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
6f00: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
6f10: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
6f20: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
6f30: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
6f40: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
6f50: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
6f60: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
6f70: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
6f80: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6f90: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
6fa0: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6fb0: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
6fc0: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
6fd0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
6fe0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
6ff0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
7000: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
7010: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
7020: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
7030: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
7040: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
7050: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
7060: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
7070: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
7080: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
7090: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
70a0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
70b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
70c0: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
70d0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
70e0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
70f0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
7100: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
7110: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
7120: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
7130: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
7140: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
7150: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
7160: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
7170: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
7180: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
7190: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
71a0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
71b0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
71c0: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
71d0: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
71e0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
71f0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
7200: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
7210: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
7220: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
7230: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
7240: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
7250: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
7260: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
7270: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
7280: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
7290: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
72a0: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
72b0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
72c0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
72d0: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
72e0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
72f0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
7300: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
7310: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
7320: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
7330: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
7340: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7350: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
7360: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
7370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7380: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
7390: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
73a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
73b0: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
73c0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
73d0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
73e0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
73f0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
7400: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7410: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
7420: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
7430: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
7440: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
7450: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
7460: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
7470: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
7480: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
7490: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
74a0: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
74b0: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
74c0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
74d0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
74e0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
74f0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
7500: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
7510: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
7520: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
7530: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
7540: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
7550: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
7560: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
7570: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7580: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
7590: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
75a0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
75b0: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
75c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
75d0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
75e0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
75f0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
7600: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7610: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
7620: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
7630: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
7640: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
7650: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7660: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7670: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
7680: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7690: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
76a0: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
76b0: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
76c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
76d0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
76e0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
76f0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
7700: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
7710: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
7720: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
7730: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
7740: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
7750: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
7760: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
7770: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7780: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
7790: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
77a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
77b0: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
77c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
77d0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
77e0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
77f0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
7800: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
7810: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
7820: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
7830: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
7840: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7850: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
7860: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
7870: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
7880: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
7890: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
78a0: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
78b0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
78c0: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
78d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
78e0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
78f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7900: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
7910: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
7920: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7930: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
7940: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
7950: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
7960: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
7970: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
7980: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
7990: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
79a0: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
79b0: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
79c0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
79d0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
79e0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
79f0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
7a00: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
7a10: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
7a20: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
7a30: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
7a40: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
7a50: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
7a60: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
7a70: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
7a80: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
7a90: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
7aa0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7ab0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
7ac0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7ad0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
7ae0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
7af0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
7b00: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
7b10: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
7b20: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7b30: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
7b40: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
7b50: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
7b60: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
7b70: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
7b80: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
7b90: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
7ba0: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
7bb0: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
7bc0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
7bd0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
7be0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
7bf0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
7c00: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
7c10: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
7c20: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
7c30: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
7c40: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
7c50: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
7c60: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
7c70: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
7c80: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
7c90: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
7ca0: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
7cb0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
7cc0: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
7cd0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
7ce0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
7cf0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
7d00: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
7d10: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
7d20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
7d30: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
7d40: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
7d50: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
7d60: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
7d70: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
7d80: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
7d90: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
7da0: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
7db0: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
7dc0: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
7dd0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
7de0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
7df0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
7e00: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
7e10: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
7e20: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
7e30: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
7e40: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
7e50: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
7e60: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
7e70: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
7e80: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
7e90: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
7ea0: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
7eb0: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
7ec0: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
7ed0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
7ee0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
7ef0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
7f00: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
7f10: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
7f20: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
7f30: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
7f40: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
7f50: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7f60: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7f70: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7f80: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7f90: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7fa0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7fb0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7fc0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7fd0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7fe0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7ff0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
8000: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
8010: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
8020: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
8030: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8040: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8050: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8060: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8070: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8080: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8090: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
80a0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
80b0: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
80c0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
80d0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
80e0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
80f0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8100: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
8110: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
8120: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8130: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8140: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8150: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8160: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8170: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8180: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8190: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
81a0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
81b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
81c0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
81d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
81e0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
81f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8200: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
8210: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8220: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8230: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8240: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8250: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8260: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8270: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8280: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8290: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
82a0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
82b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
82c0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
82d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
82e0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
82f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8300: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
8310: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8320: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8330: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8340: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8350: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8360: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8370: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8380: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8390: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
83a0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
83b0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
83c0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
83d0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
83e0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
83f0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8400: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8410: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8420: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8430: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8440: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8450: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8460: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8470: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8480: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8490: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
84a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
84b0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
84c0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
84d0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
84e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
84f0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8500: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8510: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8520: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8530: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8540: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8550: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
8560: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8580: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8590: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
85a0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
85b0: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
85c0: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
85d0: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
85e0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
85f0: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8600: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8610: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
8620: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
8630: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
8640: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
8650: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
8660: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8670: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8680: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8690: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
86a0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
86b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
86c0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
86d0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
86e0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
86f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8700: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8710: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8720: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8730: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8740: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
8750: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
8760: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8770: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8780: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8790: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
87a0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
87b0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
87c0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
87d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
87e0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
87f0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8800: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8810: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
8820: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
8830: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8840: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
8850: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8860: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8870: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8880: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8890: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
88a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
88b0: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
88c0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
88d0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
88e0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
88f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8900: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8910: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8920: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8930: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8940: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8950: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8960: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8970: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8980: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8990: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
89a0: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
89b0: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
89c0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
89d0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
89e0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
89f0: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8a00: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8a10: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8a20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a30: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8a40: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8a50: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8a60: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8a70: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8a80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a90: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8aa0: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8ab0: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8ac0: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8ad0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8ae0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8af0: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8b00: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8b10: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8b20: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8b30: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8b40: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8b50: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8b60: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8b70: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8b80: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8b90: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
8ba0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
8bb0: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
8bc0: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
8bd0: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
8be0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
8bf0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8c00: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
8c10: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8c20: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
8c30: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
8c40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
8c50: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
8c60: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
8c70: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
8c80: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
8c90: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8ca0: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
8cb0: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
8cc0: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
8cd0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
8ce0: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
8cf0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
8d00: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
8d10: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
8d20: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
8d30: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
8d40: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
8d50: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
8d60: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
8d70: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
8d80: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
8d90: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
8da0: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
8db0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
8dc0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
8dd0: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
8de0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c  is defined..** <
8df0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  ul>.** <li>[[SQL
8e00: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8e10: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
8e20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8e30: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
8e40: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
8e50: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
8e60: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
8e70: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
8e80: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
8e90: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
8ea0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
8eb0: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
8ec0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
8ed0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
8ee0: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
8ef0: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
8f00: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
8f10: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
8f20: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
8f30: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
8f40: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
8f50: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
8f60: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
8f70: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
8f80: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8f90: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
8fa0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8fb0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8fc0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8fd0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
8fe0: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
8ff0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
9000: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
9010: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9020: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9030: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9040: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9050: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9060: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9070: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
9080: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9090: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
90a0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
90b0: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
90c0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
90d0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
90e0: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
90f0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
9100: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
9110: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9120: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9130: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9140: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9150: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9160: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9170: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
9180: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
9190: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
91a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
91b0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
91c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
91d0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
91e0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
91f0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
9200: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
9210: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9220: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9230: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9240: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9250: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9260: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  e the [sqlite3_f
9270: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64  ile_control()] d
9280: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
9290: 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
92a0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
92b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
92c0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
92d0: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72  D]].** No longer
92e0: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c   in use..**.** <
92f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9300: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20  L_SYNC]].** The 
9310: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9320: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  NC] opcode is ge
9330: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9340: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ly by SQLite and
9350: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20  .** sent to the 
9360: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  VFS immediately 
9370: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63  before the xSync
9380: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
9390: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62  ed on a.** datab
93a0: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  ase file descrip
93b0: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  tor. Or, if the 
93c0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
93d0: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20  not invoked .** 
93e0: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72  because the user
93f0: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   has configured 
9400: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20  SQLite with .** 
9410: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
9420: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9430: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74  chronous=OFF] it
9440: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70   is invoked in p
9450: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20  lace .** of the 
9460: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e  xSync method. In
9470: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65   most cases, the
9480: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
9490: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a  t passed with.**
94a0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
94b0: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65  ol is NULL. Howe
94c0: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61  ver, if the data
94d0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69  base file is bei
94e0: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20  ng synced.** as 
94f0: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d  part of a multi-
9500: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c  database commit,
9510: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f   the argument po
9520: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65  ints to a nul-te
9530: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
9540: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
9550: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d  e transactions m
9560: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69  aster-journal fi
9570: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74  le name. VFSes t
9580: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e  hat .** do not n
9590: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
95a0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
95b0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
95c0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
95d0: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20   .** should not 
95e0: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
95f0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9600: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9610: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a  s doing so may .
9620: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ** disrupt the o
9630: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9640: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9650: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9660: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9670: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9680: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
9690: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
96a0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
96b0: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20  HASETWO] opcode 
96c0: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
96d0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
96e0: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f  e.** and sent to
96f0: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61   the VFS after a
9700: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73   transaction has
9710: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20   been committed 
9720: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62  immediately.** b
9730: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ut before the da
9740: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b  tabase is unlock
9750: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64  ed. VFSes that d
9760: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
9770: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64  signal.** should
9780: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9790: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
97a0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
97b0: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73  d not call.** [s
97c0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
97d0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
97e0: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
97f0: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9800: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  the .** operatio
9810: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9820: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9830: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9840: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9850: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9860: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
9870: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9880: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9890: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
98a0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
98b0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
98c0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
98d0: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
98e0: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
98f0: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9900: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9910: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9920: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9930: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9940: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
9950: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
9960: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
9970: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
9980: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
9990: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
99a0: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
99b0: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
99c0: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
99d0: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
99e0: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
99f0: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9a00: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9a10: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9a20: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9a30: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9a40: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
9a50: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
9a60: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
9a70: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
9a80: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
9a90: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
9aa0: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9ab0: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9ac0: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9ad0: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9ae0: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9af0: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9b00: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9b10: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9b20: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9b30: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9b40: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
9b50: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
9b60: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
9b70: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
9b80: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
9b90: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
9ba0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
9bb0: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
9bc0: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
9bd0: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
9be0: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
9bf0: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
9c00: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
9c10: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
9c20: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
9c30: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
9c40: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
9c50: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
9c60: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
9c70: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
9c80: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
9c90: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9ca0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9cb0: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
9cc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9cd0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
9ce0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9cf0: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9d00: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
9d10: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
9d20: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
9d30: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9d40: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
9d50: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
9d60: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
9d70: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
9d80: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
9d90: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
9da0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
9db0: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
9dc0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
9dd0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
9de0: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
9df0: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9e00: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
9e10: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
9e20: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
9e30: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
9e40: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
9e50: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
9e60: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
9e70: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
9e80: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
9e90: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
9ea0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
9eb0: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
9ec0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
9ed0: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
9ee0: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
9ef0: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
9f00: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
9f10: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
9f20: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
9f30: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
9f40: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9f50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9f60: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
9f70: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
9f80: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
9f90: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
9fa0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
9fb0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
9fc0: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9fd0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
9fe0: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
9ff0: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a000: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a010: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a020: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a030: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a040: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a050: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a060: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a070: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a080: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a090: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a0a0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a0b0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a0c0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a0d0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a0e0: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a0f0: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a100: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a110: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a120: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a130: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a140: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a150: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a160: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a170: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a180: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a190: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a1a0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a1b0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a1c0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a1d0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a1e0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a1f0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a200: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a210: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a220: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a230: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
a240: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a250: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a260: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a270: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
a280: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
a290: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a2a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
a2b0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a2c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2d0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a2e0: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
a2f0: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
a300: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
a310: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
a320: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
a330: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
a340: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
a350: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
a360: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
a370: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
a380: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
a390: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
a3a0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
a3b0: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
a3c0: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
a3d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a3e0: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
a3f0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a400: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
a410: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
a420: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
a430: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
a440: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
a450: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
a460: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
a470: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
a480: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
a490: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
a4a0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
a4b0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
a4c0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
a4d0: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
a4e0: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
a4f0: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
a500: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
a510: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a520: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
a530: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a540: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
a550: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
a560: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
a570: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
a580: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
a590: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
a5a0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
a5b0: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
a5c0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
a5d0: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
a5e0: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
a5f0: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
a600: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
a610: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
a620: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
a630: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
a640: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
a650: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
a660: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
a670: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
a680: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
a690: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
a6a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a6b0: 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e  TL_PRAGMA]].** ^
a6c0: 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47  Whenever a [PRAG
a6d0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  MA] statement is
a6e0: 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c   parsed, an [SQL
a6f0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a700: 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  ] .** file contr
a710: 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68  ol is sent to th
a720: 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e open [sqlite3_
a730: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72  file] object cor
a740: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f  responding.** to
a750: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a760: 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  le to which the 
a770: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
a780: 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72   refers. ^The ar
a790: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
a7a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a7b0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a7c0: 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20  rol is an array 
a7d0: 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  of.** pointers t
a7e0: 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a  o strings (char*
a7f0: 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  *) in which the 
a800: 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f  second element o
a810: 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69  f the array.** i
a820: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
a830: 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65  e pragma and the
a840: 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69   third element i
a850: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
a860: 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20  o the.** pragma 
a870: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70  or NULL if the p
a880: 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67  ragma has no arg
a890: 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e  ument.  ^The han
a8a0: 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b  dler for an.** [
a8b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a8c0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a8d0: 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79  l can optionally
a8e0: 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20   make the first 
a8f0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  element.** of th
a900: 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e  e char** argumen
a910: 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  t point to a str
a920: 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
a930: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
a940: 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20  tf()].** or the 
a950: 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74  equivalent and t
a960: 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  hat string will 
a970: 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c  become the resul
a980: 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  t of the pragma 
a990: 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  or.** the error 
a9a0: 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70  message if the p
a9b0: 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66  ragma fails. ^If
a9c0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
a9d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a9e0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a9f0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ns [SQLITE_NOTFO
aa00: 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61  UND], then norma
aa10: 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70  l .** [PRAGMA] p
aa20: 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e  rocessing contin
aa30: 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ues.  ^If the [S
aa40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aa50: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
aa60: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
aa70: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68  ITE_OK], then th
aa80: 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73  e parser assumes
aa90: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53   that the.** VFS
aaa0: 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65   has handled the
aab0: 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61   PRAGMA itself a
aac0: 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65  nd the parser ge
aad0: 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a  nerates a no-op.
aae0: 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
aaf0: 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ement.  ^If the 
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab10: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ab20: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
ab30: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
ab40: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
ab50: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
ab60: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
ab70: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
ab80: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
ab90: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
aba0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
abb0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
abc0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
abd0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
abe0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
abf0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
ac00: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
ac10: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
ac20: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
ac30: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
ac40: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
ac50: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
ac60: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
ac70: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
ac80: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
ac90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
aca0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
acb0: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
acc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
acd0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
ace0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
acf0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
ad00: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
ad10: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
ad20: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ad30: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ad40: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ad50: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ad60: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ad70: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ad80: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
ad90: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ada0: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
adb0: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
adc0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
add0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
ade0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
adf0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
ae00: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
ae10: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
ae20: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
ae30: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
ae40: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
ae50: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
ae60: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
ae70: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
ae80: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
ae90: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
aea0: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
aeb0: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
aec0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
aed0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
aee0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
aef0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
af00: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
af10: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
af20: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
af30: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
af40: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
af50: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
af60: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
af70: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
af80: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
af90: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
afa0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
afb0: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
afc0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
afd0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
afe0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
aff0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b000: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b010: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b020: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b030: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b040: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b050: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b060: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b070: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b080: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b090: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b0a0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b0b0: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b0c0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b0d0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b0e0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b0f0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b100: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b110: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b120: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b130: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b140: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b150: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b160: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b170: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b180: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b190: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b1a0: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b1b0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b1c0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b1d0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b1e0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b1f0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b200: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b210: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b220: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b230: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b240: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b250: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b260: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b270: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b280: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b290: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b2a0: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b2b0: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b2c0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b2d0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b2e0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b2f0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b300: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b310: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b320: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b330: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b340: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b350: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b360: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b370: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b380: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b390: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b3a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b3b0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b3c0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b3d0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b3e0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b3f0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b400: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b410: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b420: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b430: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b440: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b450: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b460: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b470: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b480: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b490: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b4a0: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b4b0: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b4c0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b4d0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
b4e0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
b4f0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
b500: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
b510: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
b520: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
b530: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
b540: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
b550: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
b560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b570: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
b580: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
b590: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
b5a0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
b5b0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
b5c0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
b5d0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
b5e0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
b5f0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
b600: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
b610: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
b620: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
b630: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
b640: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
b650: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
b660: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
b670: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b680: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b690: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
b6a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b6b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b6c0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
b6d0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
b6e0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
b6f0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
b700: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
b710: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
b720: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
b730: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
b740: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
b750: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
b760: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
b770: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b780: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
b790: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
b7a0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
b7b0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
b7c0: 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .**.** </ul>.*/.
b7d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b7e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
b7f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
b800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b810: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
b820: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
b830: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b840: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
b850: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
b860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b870: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
b880: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
b890: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b8a0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
b8b0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
b8c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b8d0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
b8e0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
b8f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
b900: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
b910: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
b920: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
b930: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
b940: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
b950: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b960: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
b970: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
b980: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
b990: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
b9a0: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
b9b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
b9c0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
b9d0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
b9e0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
b9f0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
ba00: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
ba10: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
ba20: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
ba30: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
ba40: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
ba50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
ba60: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
ba70: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
ba80: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
ba90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
baa0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
bab0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
bac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bad0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
bae0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
baf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bb00: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
bb10: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
bb20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bb30: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
bb40: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
bb50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bb60: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
bb70: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
bb80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bb90: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
bba0: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
bbb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bbc0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bbd0: 20 20 20 20 20 20 20 32 33 0a 2f 2a 20 64 65 70         23./* dep
bbe0: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
bbf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bc00: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
bc10: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
bc20: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bc30: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
bc40: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
bc50: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
bc60: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
bc70: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
bc80: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
bc90: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
bca0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
bcb0: 53 54 5f 45 52 52 4e 4f 0a 0a 2f 2a 0a 2a 2a 20  ST_ERRNO../*.** 
bcc0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
bcd0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
bce0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
bcf0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
bd00: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
bd10: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
bd20: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
bd30: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
bd40: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
bd50: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
bd60: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
bd70: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
bd80: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
bd90: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
bda0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
bdb0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
bdc0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
bdd0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
bde0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
bdf0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
be00: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
be10: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
be20: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
be30: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
be40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
be50: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
be60: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
be70: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
be80: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
be90: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
bea0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
beb0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
bec0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
bed0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
bee0: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
bef0: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
bf00: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
bf10: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
bf20: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
bf30: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
bf40: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
bf50: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
bf60: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
bf70: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
bf80: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
bf90: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
bfa0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
bfb0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
bfc0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
bfd0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
bfe0: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
bff0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
c000: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
c010: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
c020: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
c030: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
c040: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
c050: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c060: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
c070: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
c080: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
c090: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
c0a0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
c0b0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
c0c0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
c0d0: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
c0e0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
c0f0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
c100: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
c110: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
c120: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
c130: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
c140: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
c150: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
c160: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
c170: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
c180: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
c190: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
c1a0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
c1b0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
c1c0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
c1d0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
c1e0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
c1f0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
c200: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
c210: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
c220: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
c230: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
c240: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
c250: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
c260: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
c270: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
c280: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
c290: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
c2a0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
c2b0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
c2c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
c2d0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
c2e0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
c2f0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
c300: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
c310: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
c320: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
c330: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
c340: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
c350: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
c360: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
c370: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
c380: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
c390: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
c3a0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
c3b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
c3c0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
c3d0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
c3e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c3f0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
c400: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
c410: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
c420: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
c430: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
c440: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
c450: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
c460: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
c470: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
c480: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
c490: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
c4a0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
c4b0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
c4c0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
c4d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
c4e0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
c4f0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
c500: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
c510: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
c520: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
c530: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
c540: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
c550: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
c560: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
c570: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
c580: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
c590: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
c5a0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
c5b0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
c5c0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
c5d0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
c5e0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
c5f0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
c600: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
c610: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
c620: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
c630: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
c640: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
c650: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
c660: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
c670: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
c680: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
c690: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
c6a0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
c6b0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
c6c0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
c6d0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
c6e0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
c6f0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
c700: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c710: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
c720: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
c730: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
c740: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
c750: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
c760: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
c770: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
c780: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
c790: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
c7a0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
c7b0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
c7c0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
c7d0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
c7e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c7f0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
c800: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
c810: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
c820: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
c830: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
c840: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
c850: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
c860: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
c870: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
c880: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c890: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
c8a0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
c8b0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
c8c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
c8d0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
c8e0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
c8f0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
c900: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
c910: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
c920: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
c930: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
c940: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
c950: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
c960: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
c970: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
c980: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
c990: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
c9a0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
c9b0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
c9c0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
c9d0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
c9e0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
c9f0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
ca00: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ca10: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
ca20: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ca30: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
ca40: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ca50: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
ca60: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ca70: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
ca80: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ca90: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
caa0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
cab0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
cac0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
cad0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
cae0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
caf0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cb00: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
cb10: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
cb20: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
cb30: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
cb40: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
cb50: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
cb60: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
cb70: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
cb80: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
cb90: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
cba0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
cbb0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
cbc0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
cbd0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
cbe0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
cbf0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
cc00: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
cc10: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
cc20: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
cc30: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
cc40: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
cc50: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
cc60: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
cc70: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
cc80: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
cc90: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
cca0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
ccb0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
ccc0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
ccd0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
cce0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
ccf0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
cd00: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
cd10: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
cd20: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
cd30: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
cd40: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
cd50: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
cd60: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
cd70: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
cd80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
cd90: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cda0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
cdb0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
cdc0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
cdd0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
cde0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
cdf0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
ce00: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
ce10: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
ce20: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
ce30: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
ce40: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
ce50: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
ce60: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
ce70: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
ce80: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
ce90: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
cea0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
ceb0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
cec0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
ced0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
cee0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
cef0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
cf00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
cf10: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
cf20: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
cf30: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
cf40: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
cf50: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
cf60: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
cf70: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
cf80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
cf90: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
cfa0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
cfb0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
cfc0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
cfd0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
cfe0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
cff0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
d000: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
d010: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
d020: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
d030: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
d040: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
d050: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
d060: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
d070: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
d080: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
d090: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
d0a0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
d0b0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
d0c0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
d0d0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
d0e0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
d0f0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
d100: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
d110: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
d120: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
d130: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
d140: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
d150: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
d160: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
d170: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
d180: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
d190: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
d1a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
d1b0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
d1c0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
d1d0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
d1e0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
d1f0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
d200: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
d210: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
d220: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
d230: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
d240: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
d250: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
d260: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
d270: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
d280: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
d290: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
d2a0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
d2b0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
d2c0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
d2d0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
d2e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
d2f0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
d300: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
d310: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
d320: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
d330: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
d340: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
d350: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
d360: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
d370: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
d380: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
d390: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
d3a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
d3b0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
d3c0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
d3d0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
d3e0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
d3f0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
d400: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
d410: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
d420: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
d430: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
d440: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
d450: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
d460: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
d470: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
d480: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d490: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
d4a0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
d4b0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
d4c0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
d4d0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
d4e0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
d4f0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
d500: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
d510: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
d520: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
d530: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
d540: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
d550: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
d560: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
d570: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
d580: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
d590: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
d5a0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
d5b0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
d5c0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
d5d0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
d5e0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
d5f0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
d600: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
d610: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
d620: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
d630: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
d640: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
d650: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
d660: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
d670: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
d680: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
d690: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
d6a0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
d6b0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
d6c0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
d6d0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
d6e0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
d6f0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
d700: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
d710: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
d720: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
d730: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
d740: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
d750: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
d760: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
d770: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
d780: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
d790: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
d7a0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
d7b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
d7c0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
d7d0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
d7e0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
d7f0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
d800: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
d810: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
d820: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
d830: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
d840: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
d850: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
d860: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
d870: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
d880: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
d890: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
d8a0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
d8b0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
d8c0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
d8d0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
d8e0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
d8f0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
d900: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
d910: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
d920: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
d930: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
d940: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
d950: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
d960: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
d970: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
d980: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
d990: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
d9a0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
d9b0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
d9c0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
d9d0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
d9e0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
d9f0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
da00: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
da10: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
da20: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
da30: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
da40: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
da50: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
da60: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
da70: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
da80: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
da90: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
daa0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
dab0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
dac0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
dad0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
dae0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
daf0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
db00: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
db10: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
db20: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
db30: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
db40: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
db50: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
db60: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
db70: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
db80: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
db90: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
dba0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
dbb0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
dbc0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
dbd0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
dbe0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
dbf0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
dc00: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
dc10: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
dc20: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
dc30: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
dc40: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
dc50: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
dc60: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
dc70: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
dc80: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
dc90: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
dca0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
dcb0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
dcc0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
dcd0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
dce0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
dcf0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
dd00: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
dd10: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
dd20: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
dd30: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
dd40: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
dd50: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
dd60: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
dd70: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
dd80: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
dd90: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
dda0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
ddb0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
ddc0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
ddd0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
dde0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
ddf0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
de00: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
de10: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
de20: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
de30: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
de40: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
de50: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
de60: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
de70: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
de80: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
de90: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
dea0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
deb0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
dec0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
ded0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
dee0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
def0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
df00: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
df10: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
df20: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
df30: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
df40: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
df50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
df60: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
df70: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
df80: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
df90: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dfa0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
dfb0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
dfc0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
dfd0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
dfe0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
dff0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e000: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
e010: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
e020: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
e030: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e040: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
e050: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
e060: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
e070: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
e080: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
e090: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
e0a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
e0b0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e0c0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
e0d0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
e0e0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e0f0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
e100: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
e110: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
e120: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
e130: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
e140: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
e150: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
e160: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
e170: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
e180: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
e190: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
e1a0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
e1b0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
e1c0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
e1d0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e1e0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e1f0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
e200: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
e210: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
e220: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
e230: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
e240: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
e250: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
e260: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
e270: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
e280: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
e290: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e2a0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e2b0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
e2c0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
e2d0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
e2e0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
e2f0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
e300: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
e310: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
e320: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e330: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e340: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
e350: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
e360: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
e370: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
e380: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e390: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e3a0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
e3b0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
e3c0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
e3d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e3e0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
e3f0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e400: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e410: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
e420: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
e430: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
e440: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
e450: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
e460: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
e470: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
e480: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
e490: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
e4a0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
e4b0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
e4c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
e4d0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
e4e0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
e4f0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
e500: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
e510: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
e520: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
e530: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
e540: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
e550: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
e560: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
e570: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
e580: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
e590: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e5a0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
e5b0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
e5c0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
e5d0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e5e0: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
e5f0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e600: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
e610: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
e620: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
e630: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e640: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
e650: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
e660: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
e670: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
e680: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
e690: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
e6a0: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
e6b0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
e6c0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
e6d0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
e6e0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
e6f0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
e700: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
e710: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
e720: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
e730: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
e740: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
e750: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
e760: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
e770: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
e780: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
e790: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
e7a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e7b0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
e7c0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
e7d0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
e7e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e7f0: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
e800: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
e810: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
e820: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
e830: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
e840: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
e850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e860: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
e870: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
e880: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
e890: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
e8a0: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
e8b0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
e8c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e8d0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
e8e0: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
e8f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e900: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
e910: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
e920: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
e930: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
e940: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
e950: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
e960: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
e970: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
e980: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
e990: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
e9a0: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
e9b0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
e9c0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
e9d0: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
e9e0: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
e9f0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
ea00: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
ea10: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
ea20: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
ea30: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
ea40: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
ea50: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
ea60: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
ea70: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
ea80: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
ea90: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
eaa0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
eab0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
eac0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
ead0: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
eae0: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
eaf0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
eb00: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
eb10: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
eb20: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
eb30: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
eb40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
eb50: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
eb60: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
eb70: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
eb80: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
eb90: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
eba0: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
ebb0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
ebc0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
ebd0: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
ebe0: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
ebf0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
ec00: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
ec10: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
ec20: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
ec30: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
ec40: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
ec50: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
ec60: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
ec70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
ec80: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
ec90: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
eca0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
ecb0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
ecc0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
ecd0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
ece0: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
ecf0: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
ed00: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
ed10: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
ed20: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
ed30: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
ed40: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
ed50: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
ed60: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
ed70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ed80: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
ed90: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
eda0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
edb0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
edc0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
edd0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ede0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
edf0: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
ee00: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
ee10: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
ee20: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
ee30: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
ee40: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
ee50: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
ee60: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
ee70: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
ee80: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
ee90: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
eea0: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
eeb0: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
eec0: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
eed0: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
eee0: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
eef0: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
ef00: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
ef10: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
ef20: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
ef30: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
ef40: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
ef50: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
ef60: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
ef70: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
ef80: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
ef90: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
efa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
efb0: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
efc0: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
efd0: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
efe0: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
eff0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
f000: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f010: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
f020: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
f030: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f040: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
f050: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
f060: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
f070: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
f080: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
f090: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
f0a0: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
f0b0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
f0c0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
f0d0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f0e0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
f0f0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
f100: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
f110: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f120: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
f130: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
f140: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
f150: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
f160: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
f170: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f180: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
f190: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
f1a0: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
f1b0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
f1c0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
f1d0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
f1e0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
f1f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f200: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
f210: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
f220: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f230: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
f240: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f250: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
f260: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
f270: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
f280: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
f290: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
f2a0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
f2b0: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
f2c0: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
f2d0: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
f2e0: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
f2f0: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
f300: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
f310: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
f320: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
f330: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
f340: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
f350: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
f360: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
f370: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
f380: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
f390: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
f3a0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
f3b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
f3c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
f3d0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
f3e0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
f3f0: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
f400: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
f410: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f420: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
f430: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
f440: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
f450: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
f460: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
f470: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
f480: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
f490: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
f4a0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
f4b0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
f4c0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
f4d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f4e0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
f4f0: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
f500: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
f510: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
f520: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
f530: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
f540: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
f550: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
f560: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f570: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
f580: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
f590: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
f5a0: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
f5b0: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
f5c0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
f5d0: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
f5e0: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
f5f0: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
f600: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
f610: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
f620: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
f630: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
f640: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
f650: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f660: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
f670: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
f680: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
f690: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
f6a0: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
f6b0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
f6c0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
f6d0: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
f6e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
f6f0: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
f700: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
f710: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
f720: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
f730: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f740: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
f750: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
f760: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
f770: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
f780: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
f790: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f7a0: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
f7b0: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
f7c0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
f7d0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
f7e0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
f7f0: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
f800: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
f810: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
f820: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
f830: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
f840: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f850: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
f860: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
f870: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
f880: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
f890: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
f8a0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
f8b0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
f8c0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
f8d0: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
f8e0: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
f8f0: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
f900: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
f910: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
f920: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
f930: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
f940: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
f950: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
f960: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
f970: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
f980: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
f990: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
f9a0: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
f9b0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
f9c0: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
f9d0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f9e0: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
f9f0: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
fa00: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
fa10: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
fa20: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
fa30: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
fa40: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
fa50: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
fa60: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
fa70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
fa80: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
fa90: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
faa0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
fab0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
fac0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
fad0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
fae0: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
faf0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb00: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
fb10: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
fb20: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
fb30: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
fb40: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
fb50: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
fb60: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fb70: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
fb80: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
fb90: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
fba0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
fbb0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
fbc0: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
fbd0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fbe0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
fbf0: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
fc00: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
fc10: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
fc20: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
fc30: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
fc40: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
fc50: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
fc60: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
fc70: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
fc80: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
fc90: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
fca0: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
fcb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
fcc0: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
fcd0: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
fce0: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
fcf0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
fd00: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
fd10: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
fd20: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
fd30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
fd40: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fd50: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
fd60: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
fd70: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
fd80: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
fd90: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
fda0: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
fdb0: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
fdc0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fdd0: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
fde0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
fdf0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
fe00: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
fe10: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
fe20: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
fe30: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
fe40: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
fe50: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
fe60: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
fe70: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
fe80: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
fe90: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
fea0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
feb0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
fec0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
fed0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
fee0: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
fef0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
ff00: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
ff10: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
ff20: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
ff30: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
ff40: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
ff50: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
ff60: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
ff70: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
ff80: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
ff90: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
ffa0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
ffb0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
ffc0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
ffd0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
ffe0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
fff0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
10000 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
10010 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
10020 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
10030 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
10040 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
10050 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10060 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
10070 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
10080 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
10090 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
100a0 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
100b0 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
100c0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
100d0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
100e0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
100f0 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
10100 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
10110 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
10120 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
10130 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
10140 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
10150 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
10160 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10170 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
10180 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
10190 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
101a0 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
101b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
101c0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
101d0 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
101e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
101f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
10200 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
10210 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
10220 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
10230 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
10240 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
10250 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
10260 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
10270 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
10280 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
10290 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
102a0 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
102b0 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
102c0 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
102d0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
102e0 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
102f0 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
10300 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
10310 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
10320 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10330 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
10340 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
10350 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
10360 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
10370 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
10380 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
10390 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
103a0 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
103b0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
103c0 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
103d0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
103e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
103f0 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
10400 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10410 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
10420 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  connections.**.*
10430 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
10440 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
10450 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
10460 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
10470 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
10480 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
10490 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
104a0 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
104b0 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
104c0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
104d0 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
104e0 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
104f0 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
10500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
10510 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
10520 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
10530 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
10540 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
10550 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10560 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
10570 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
10580 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10590 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
105a0 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
105b0 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
105c0 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
105d0 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
105e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
105f0 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
10600 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
10610 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
10620 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10630 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
10640 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
10650 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
10660 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
10670 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
10680 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
10690 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
106a0 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
106b0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
106c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
106d0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
106e0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
106f0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
10700 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
10710 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
10720 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
10730 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
10740 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
10750 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
10760 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
10770 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
10780 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
10790 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
107a0 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
107b0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
107c0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
107d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
107e0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
107f0 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
10800 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
10810 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
10820 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
10830 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
10840 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
10850 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
10860 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
10870 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
10880 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
10890 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
108a0 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
108b0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
108c0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
108d0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
108e0 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
108f0 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
10900 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
10910 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
10920 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
10930 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
10940 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
10950 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
10960 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
10970 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
10980 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
10990 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
109a0 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
109b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
109c0 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
109d0 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
109e0 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
109f0 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
10a00 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
10a10 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
10a20 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
10a30 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
10a40 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
10a50 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
10a60 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
10a70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10a80 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
10a90 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
10aa0 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
10ab0 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
10ac0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
10ad0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
10ae0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
10af0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
10b00 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
10b10 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
10b20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
10b30 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
10b40 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
10b50 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
10b60 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
10b70 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
10b80 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
10b90 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
10ba0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
10bb0 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
10bc0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
10bd0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
10be0 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
10bf0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
10c00 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
10c10 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
10c20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
10c30 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
10c40 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
10c50 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
10c60 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
10c70 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
10c80 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
10c90 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
10ca0 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
10cb0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
10cc0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
10cd0 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
10ce0 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
10cf0 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
10d00 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
10d10 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
10d20 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
10d30 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
10d40 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
10d50 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
10d60 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
10d70 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
10d80 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
10d90 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
10da0 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
10db0 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
10dc0 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
10dd0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
10de0 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
10df0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
10e00 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
10e10 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
10e20 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
10e30 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
10e40 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
10e50 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
10e60 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
10e70 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
10e80 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
10e90 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
10ea0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
10eb0 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
10ec0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
10ed0 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
10ee0 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
10ef0 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
10f00 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
10f10 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
10f20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
10f30 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
10f40 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
10f50 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
10f60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
10f70 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a    For example,.*
10f80 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
10f90 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
10fa0 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
10fb0 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
10fc0 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
10fd0 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
10fe0 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
10ff0 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
11000 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
11010 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
11020 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
11030 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
11040 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
11050 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
11060 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
11070 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
11080 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
11090 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
110a0 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
110b0 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
110c0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
110d0 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
110e0 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
110f0 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
11100 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
11110 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
11120 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
11130 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
11140 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
11150 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
11160 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11170 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
11180 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
11190 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
111a0 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
111b0 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
111c0 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
111d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
111e0 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
111f0 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
11200 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11210 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
11220 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
11230 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
11240 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
11250 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
11260 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
11270 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
11280 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
11290 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
112a0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
112b0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
112c0 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
112d0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
112e0 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
112f0 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
11300 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
11310 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
11320 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
11330 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
11340 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
11350 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
11360 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
11370 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
11380 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
11390 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
113a0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
113b0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
113c0 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
113d0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
113e0 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
113f0 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
11400 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
11410 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
11420 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
11430 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
11440 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
11450 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
11460 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
11470 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
11480 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
11490 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
114a0 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
114b0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
114c0 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
114d0 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
114e0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
114f0 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
11500 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
11510 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
11520 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
11530 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
11540 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
11550 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
11560 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
11570 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
11580 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
11590 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
115a0 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
115b0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
115c0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
115d0 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
115e0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
115f0 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
11600 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
11610 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
11620 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
11630 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
11640 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
11650 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
11660 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
11670 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
11680 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
11690 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
116a0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
116b0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
116c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
116d0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
116e0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
116f0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
11700 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
11710 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
11720 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
11730 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
11740 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
11750 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11760 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
11770 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
11780 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
11790 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
117a0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
117b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
117c0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
117d0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
117e0 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
117f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11800 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
11810 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
11820 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
11830 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
11840 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
11850 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
11860 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
11870 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
11880 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11890 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
118a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
118b0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
118c0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
118d0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
118e0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
118f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11900 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11910 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11920 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
11930 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
11940 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
11950 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
11960 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
11970 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
11980 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
11990 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
119a0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
119b0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
119c0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
119d0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
119e0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
119f0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
11a00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
11a10 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
11a20 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
11a30 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
11a40 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
11a50 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
11a60 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
11a70 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
11a80 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
11a90 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
11aa0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
11ab0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
11ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11ad0 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
11ae0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11af0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
11b00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11b10 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
11b20 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
11b30 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
11b40 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11b50 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11b60 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11b70 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11b80 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11b90 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
11ba0 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
11bb0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
11bc0 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
11bd0 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
11be0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
11bf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11c00 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
11c10 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
11c20 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
11c30 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
11c40 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
11c50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11c60 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
11c70 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
11c80 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
11c90 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
11ca0 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
11cb0 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
11cc0 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
11cd0 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
11ce0 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
11cf0 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
11d00 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
11d10 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
11d20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11d30 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
11d40 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
11d50 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11d60 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11d70 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11d80 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11d90 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11da0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11db0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11dc0 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
11dd0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
11de0 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
11df0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11e00 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
11e10 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
11e20 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
11e30 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
11e40 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
11e50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11e60 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11e70 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11e80 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
11e90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
11ea0 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
11eb0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
11ec0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
11ed0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
11ee0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
11ef0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
11f00 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
11f10 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
11f20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
11f30 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
11f40 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
11f50 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
11f60 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
11f70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11f80 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
11f90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
11fa0 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
11fb0 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
11fc0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
11fd0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
11fe0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
11ff0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12000 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
12010 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
12020 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
12030 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
12040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12050 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12060 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
12070 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
12080 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
12090 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
120a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
120b0 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
120c0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
120d0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
120e0 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
120f0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
12100 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
12110 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12120 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12130 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12140 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12150 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12160 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
12170 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
12180 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
12190 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
121a0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
121b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
121c0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
121d0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
121e0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
121f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12200 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
12210 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12220 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12230 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12240 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12250 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
12260 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12270 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12280 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12290 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
122a0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
122b0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
122c0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
122d0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
122e0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
122f0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
12300 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
12310 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12320 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
12330 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
12340 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
12350 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12360 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
12370 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
12380 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
12390 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
123a0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
123b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
123c0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
123d0 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
123e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
123f0 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
12400 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12410 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12420 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
12430 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12440 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
12450 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12460 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12470 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12480 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12490 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
124a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
124b0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
124c0 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
124d0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
124e0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
124f0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
12500 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
12510 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
12520 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
12530 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
12540 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
12550 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
12560 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
12570 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
12580 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
12590 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
125a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
125b0 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
125c0 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
125d0 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
125e0 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
125f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12600 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
12610 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12620 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
12630 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
12640 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
12650 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
12660 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
12670 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
12680 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
12690 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
126a0 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
126b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
126c0 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
126d0 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
126e0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
126f0 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
12700 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
12710 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
12720 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
12730 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
12740 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
12750 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12760 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
12770 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
12780 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
12790 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
127a0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
127b0 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
127c0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
127d0 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
127e0 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
127f0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12800 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
12810 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
12820 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
12830 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
12840 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
12850 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
12860 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
12870 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
12880 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
12890 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
128a0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
128b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
128c0 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
128d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
128e0 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
128f0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
12900 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
12910 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
12920 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
12930 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63  se for.** scratc
12940 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65  h memory.  There
12950 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
12960 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72  ents:  A pointer
12970 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
12980 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
12990 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
129a0 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
129b0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
129c0 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
129d0 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
129e0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
129f0 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
12a00 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
12a10 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
12a20 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a  ons (N).  The sz
12a30 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  .** argument mus
12a40 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20  t be a multiple 
12a50 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69  of 16..** The fi
12a60 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
12a70 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  t be a pointer t
12a80 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  o an 8-byte alig
12a90 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66  ned buffer.** of
12aa0 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
12ab0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
12ac0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12ad0 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e  use no more than
12ae0 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66   two scratch buf
12af0 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e  fers per thread.
12b00 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64    So.** N should
12b10 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65   be set to twice
12b20 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61   the expected ma
12b30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
12b40 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c  threads..** ^SQL
12b50 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
12b60 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68  equire a scratch
12b70 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
12b80 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
12b90 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
12ba0 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66  e page size. ^If
12bb0 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
12bc0 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
12bd0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12be0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
12bf0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
12c00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12c10 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
12c20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12c30 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
12c40 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
12c50 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64  mory needed.</dd
12c60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12c70 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12c80 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
12c90 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
12ca0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12cb0 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
12cc0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
12cd0 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
12ce0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
12cf0 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
12d00 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
12d10 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
12d20 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
12d30 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
12d40 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
12d50 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
12d60 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
12d70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
12d80 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
12d90 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
12da0 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  aded using the S
12db0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
12dc0 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  CHE2 option..** 
12dd0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
12de0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12df0 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e  s option: A poin
12e00 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c  ter to 8-byte al
12e10 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
12e20 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
12e30 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
12e40 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
12e50 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
12e60 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
12e70 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
12e80 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
12e90 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
12ea0 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
12eb0 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
12ec0 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c  12 and 32768) pl
12ed0 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72  us a little extr
12ee0 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  a for each.** pa
12ef0 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
12f00 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a   page header siz
12f10 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79  e is 20 to 40 by
12f20 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  tes depending on
12f30 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63  .** the host arc
12f40 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20  hitecture.  ^It 
12f50 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
12f60 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
12f70 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f  ed memory,.** to
12f80 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c   make sz a littl
12f90 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68  e too large.  Th
12fa0 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
12fb0 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
12fc0 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
12fd0 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
12fe0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
12ff0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
13000 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
13010 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
13020 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13030 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
13040 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
13050 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
13060 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
13070 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e  dds to cache.  ^
13080 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
13090 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
130a0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
130b0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
130c0 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
130d0 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
130e0 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
130f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
13100 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
13110 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
13120 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
13130 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
13140 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65  ument must.** be
13150 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
13160 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f  -byte boundary o
13170 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
13180 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
13190 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  ** will be undef
131a0 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ined.</dd>.**.**
131b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
131c0 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
131d0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
131e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
131f0 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
13200 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
13210 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
13220 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
13230 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
13240 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
13250 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
13260 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
13270 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79  ovided.** for by
13280 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13290 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51  SCRATCH] and [SQ
132a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
132b0 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65  CACHE]..** There
132c0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
132d0 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20  ents: An 8-byte 
132e0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
132f0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
13300 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
13310 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
13320 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
13330 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
13340 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
13350 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
13360 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
13370 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
13380 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
13390 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
133a0 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
133b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
133c0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
133d0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
133e0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
133f0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
13400 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
13410 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13420 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
13430 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
13440 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
13450 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
13460 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
13470 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
13480 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
13490 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
134a0 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
134b0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
134c0 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
134d0 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
134e0 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
134f0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
13500 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
13510 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
13520 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
13530 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
13540 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
13550 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
13560 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
13570 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
13580 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
13590 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
135a0 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
135b0 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c  2**12. Reasonabl
135c0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20  e values.** for 
135d0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
135e0 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20  cation size are 
135f0 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a  2**5 through 2**
13600 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  8.</dd>.**.** [[
13610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13620 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
13630 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
13640 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13650 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13660 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13670 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13680 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
13690 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
136a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
136b0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
136c0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
136d0 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
136e0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
136f0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
13700 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
13710 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
13720 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
13730 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
13740 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
13750 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63  copy of the.** c
13760 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
13770 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13780 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
13790 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
137a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
137b0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
137c0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
137d0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
137e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
137f0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13800 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
13810 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13820 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
13830 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
13840 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
13850 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
13860 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
13870 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
13880 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
13890 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
138a0 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
138b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
138c0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
138d0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
138e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
138f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
13900 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13910 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
13920 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13930 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13940 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13950 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13960 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
13970 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13980 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13990 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
139a0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
139b0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
139c0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
139d0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
139e0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
139f0 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
13a00 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
13a10 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
13a20 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
13a30 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
13a40 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
13a50 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
13a60 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
13a70 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
13a80 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
13a90 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
13aa0 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
13ab0 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
13ac0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13ad0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13ae0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13af0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13b00 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13b10 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13b20 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13b30 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13b40 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13b50 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13b60 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13b70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13b80 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13b90 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
13ba0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13bb0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
13bc0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
13bd0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
13be0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13bf0 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
13c00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13c10 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
13c20 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13c30 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
13c40 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
13c50 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a  ine the default.
13c60 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
13c70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f  tion for the loo
13c80 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
13c90 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a  locator on each.
13ca0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
13cb0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66  nection].  The f
13cc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
13cd0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
13ce0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
13cf0 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
13d00 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
13d10 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
13d20 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
13d30 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
13d40 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
13d50 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
13d60 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75   the.** <i>defau
13d70 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
13d80 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
13d90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
13da0 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74  ASIDE].** verb t
13db0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
13dc0 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
13dd0 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
13de0 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
13df0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
13e00 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
13e10 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
13e20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13e30 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20  ONFIG_PCACHE2]] 
13e40 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13e50 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  G_PCACHE2</dt>.*
13e60 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
13e70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13e80 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13e90 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
13ea0 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65  to.** an [sqlite
13eb0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
13ec0 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
13ed0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
13ee0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
13ef0 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ** to a custom p
13f00 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
13f10 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51  entation.)^  ^SQ
13f20 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
13f30 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65  y of the.** obje
13f40 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66  ct and uses it f
13f50 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
13f60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
13f70 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13f80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13f90 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
13fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
13fb0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
13fc0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
13fd0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13fe0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
13ff0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14000 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  an.** [sqlite3_p
14010 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
14020 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20  object.  SQLite 
14030 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75  copies of the cu
14040 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61  rrent.** page ca
14050 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14060 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a  on into that obj
14070 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ect.)^ </dd>.**.
14080 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14090 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c  IG_LOG]] <dt>SQL
140a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
140b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20  dt>.** <dd> The 
140c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
140d0 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  G option is used
140e0 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68   to configure th
140f0 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62  e SQLite.** glob
14100 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a  al [error log]..
14110 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f  ** (^The SQLITE_
14120 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
14130 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
14140 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
14150 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
14160 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
14170 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
14180 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
14190 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
141a0 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
141b0 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
141c0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
141d0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
141e0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
141f0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14200 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
14210 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
14220 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
14230 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
14240 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
14250 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
14260 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
14270 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
14280 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
14290 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
142a0 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
142b0 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
142c0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
142d0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
142e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
142f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
14300 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
14310 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
14320 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
14330 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
14340 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
14350 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
14360 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
14370 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
14380 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14390 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
143a0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
143b0 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
143c0 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
143d0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
143e0 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
143f0 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
14400 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14410 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
14420 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
14430 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
14440 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
14450 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
14460 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
14470 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
14480 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
14490 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
144a0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
144b0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
144c0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
144d0 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
144e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
144f0 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
14500 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
14510 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
14520 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
14530 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
14540 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
14550 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
14560 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
14570 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
14580 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
14590 64 3e 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  d>^(This option 
145a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
145b0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
145c0 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  int. If non-zero
145d0 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61  , then.** URI ha
145e0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
145f0 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
14600 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
14610 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
14620 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c  andling.** is gl
14630 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
14640 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
14650 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
14660 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
14670 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64  enames.** passed
14680 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
14690 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
146a0 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  pen_v2()], [sqli
146b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
146c0 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
146d0 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
146e0 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
146f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
14700 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
14710 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
14720 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
14730 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
14740 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
14750 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
14760 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
14770 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
14780 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
14790 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
147a0 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
147b0 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
147c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
147d0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
147e0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
147f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
14800 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
14810 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
14820 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
14830 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
14840 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
14850 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
14860 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
14870 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
14880 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
14890 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
148a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
148b0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
148c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
148d0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
148e0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
148f0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
14900 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
14910 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69  ger argument whi
14920 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  ch is interprete
14930 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61  d as.** a boolea
14940 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
14950 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
14960 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
14970 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a  ing indices for.
14980 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  ** full table sc
14990 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
149a0 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68   optimizer.  ^Th
149b0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
149c0 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
149d0 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
149e0 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
149f0 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
14a00 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14a10 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
14a20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
14a30 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
14a40 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
14a50 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
14a60 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
14a70 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
14a80 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
14a90 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
14aa0 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
14ab0 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
14ac0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
14ad0 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
14ae0 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
14af0 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
14b00 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
14b10 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
14b20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
14b30 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
14b40 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
14b50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
14b60 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
14b70 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
14b80 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
14b90 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
14ba0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14bb0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
14bc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14bd0 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
14be0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14bf0 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
14c00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14c10 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
14c20 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
14c30 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
14c40 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
14c50 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
14c60 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
14c70 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
14c80 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
14c90 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
14ca0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
14cb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
14cc0 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
14cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14ce0 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
14cf0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
14d00 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
14d10 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14d20 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
14d30 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d  E_ENABLE_SQLLOG]
14d40 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
14d50 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
14d60 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14d70 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
14d80 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
14d90 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
14da0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
14db0 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
14dc0 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
14dd0 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
14de0 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
14df0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
14e00 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
14e10 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
14e20 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
14e30 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
14e40 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
14e50 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
14e60 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
14e70 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
14e80 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
14e90 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
14ea0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14eb0 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
14ec0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14ed0 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
14ee0 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
14ef0 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
14f00 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
14f10 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
14f20 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
14f30 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
14f40 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
14f50 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
14f60 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
14f70 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
14f80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
14f90 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
14fa0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
14fb0 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
14fc0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
14fd0 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
14fe0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
14ff0 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
15000 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15010 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
15020 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
15030 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
15040 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
15050 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78  his case.  An ex
15060 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74  ample of using t
15070 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  his.** configura
15080 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20  tion option can 
15090 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22  be seen in the "
150a0 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73  test_sqllog.c" s
150b0 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a  ource file in.**
150c0 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53   the canonical S
150d0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
150e0 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
150f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
15100 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  AP_SIZE]].** <dt
15110 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
15120 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  MAP_SIZE.** <dd>
15130 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  ^SQLITE_CONFIG_M
15140 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
15150 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
15160 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
15170 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
15180 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
15190 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
151a0 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
151b0 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
151c0 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
151d0 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
151e0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
151f0 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  ze limit..** ^Th
15200 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
15210 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
15220 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
15230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15240 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
15250 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
15260 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
15270 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
15280 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
15290 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
152a0 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65   control.  ^(The
152b0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
152c0 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61   mmap size.** ca
152d0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
152e0 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f  at run-time.  No
152f0 72 20 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75  r may the maximu
15300 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
15310 69 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68  ize.** exceed th
15320 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
15330 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
15340 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
15350 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
15360 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
15370 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
15380 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
15390 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
153a0 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
153b0 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
153c0 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
153d0 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
153e0 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
153f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15400 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15410 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
15420 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15430 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
15440 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
15450 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15460 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
15470 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73  iled for Windows
15480 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
15490 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
154a0 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
154b0 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a   macro defined..
154c0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
154d0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
154e0 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75  takes a 32-bit u
154f0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
15500 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70  value.** that sp
15510 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69  ecifies the maxi
15520 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20  mum size of the 
15530 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a  created heap..**
15540 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
15550 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15560 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
15570 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15580 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15590 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
155a0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
155b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
155c0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
155d0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
155e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
155f0 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
15600 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
15610 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
15620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15630 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
15640 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
15650 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
15660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15670 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
15680 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
15690 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
156a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
156b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
156c0 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
156d0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
156e0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
156f0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
15700 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
15710 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
15720 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
15730 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15740 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
15750 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
15760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15770 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
15780 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
15790 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
157a0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
157b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
157c0 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
157d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
157e0 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
157f0 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
15800 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
15810 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
15820 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
15830 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15840 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
15850 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
15860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15870 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
15880 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
15890 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
158a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
158b0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
158c0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
158d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
158e0 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
158f0 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
15900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15910 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
15920 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
15930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15940 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
15950 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
15960 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
15970 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
15980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15990 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
159a0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
159b0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
159c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
159d0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
159e0 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
159f0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
15a00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15a10 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
15a20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
15a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15a40 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15a50 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
15a60 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
15a70 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
15a80 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15a90 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15aa0 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
15ab0 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   nByte */../*.**
15ac0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
15ad0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
15ae0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
15af0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
15b00 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
15b10 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
15b20 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
15b30 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
15b40 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
15b50 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
15b60 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
15b70 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15b80 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
15b90 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
15ba0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
15bb0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
15bc0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
15bd0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
15be0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
15bf0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
15c00 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
15c10 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
15c20 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
15c30 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
15c40 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
15c50 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
15c60 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
15c70 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
15c80 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
15c90 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
15ca0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
15cb0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
15cc0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
15cd0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
15ce0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
15cf0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15d00 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
15d10 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
15d20 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
15d30 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15d40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15d50 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
15d60 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
15d70 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
15d80 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
15d90 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
15da0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
15db0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
15dc0 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
15dd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
15de0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
15df0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
15e00 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
15e10 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
15e20 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
15e30 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
15e40 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
15e50 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15e60 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
15e70 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
15e80 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
15e90 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
15ea0 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
15eb0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
15ec0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
15ed0 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
15ee0 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
15ef0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
15f00 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
15f10 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15f20 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
15f30 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
15f40 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
15f50 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
15f60 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
15f70 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
15f80 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
15f90 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
15fa0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
15fb0 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
15fc0 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
15fd0 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
15fe0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
15ff0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
16000 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
16010 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
16020 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
16030 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
16040 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
16050 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
16060 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
16070 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
16080 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
16090 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
160a0 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
160b0 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
160c0 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
160d0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
160e0 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
160f0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
16100 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
16110 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
16120 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
16130 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
16140 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
16150 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
16160 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
16170 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
16180 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
16190 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
161a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
161b0 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
161c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
161d0 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
161e0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
161f0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
16200 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
16210 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
16220 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
16230 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
16240 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
16250 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
16260 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
16270 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
16280 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
16290 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
162a0 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
162b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
162c0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
162d0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
162e0 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
162f0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
16300 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
16310 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
16320 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
16330 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
16340 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
16350 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
16360 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
16370 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
16380 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
16390 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
163a0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
163b0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
163c0 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
163d0 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
163e0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
163f0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
16400 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
16410 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
16420 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
16430 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
16440 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
16450 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
16460 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
16470 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
16480 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16490 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
164a0 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
164b0 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
164c0 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
164d0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
164e0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
164f0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
16500 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
16510 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
16520 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16530 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
16540 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
16550 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
16560 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
16570 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
16580 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
16590 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
165a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
165b0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
165c0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
165d0 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
165e0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
165f0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
16600 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
16610 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
16620 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
16630 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16640 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
16650 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
16660 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
16670 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
16680 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
16690 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
166a0 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
166b0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
166c0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
166d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
166e0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
166f0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
16700 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
16710 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
16720 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
16730 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
16740 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
16750 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
16760 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
16770 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
16780 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16790 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
167a0 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
167b0 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
167c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
167d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
167e0 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
167f0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
16800 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
16810 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
16820 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
16830 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
16840 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
16850 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
16860 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
16870 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
16880 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
16890 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
168a0 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
168b0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
168c0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
168d0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
168e0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
168f0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
16900 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
16910 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
16920 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
16930 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
16940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16950 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
16960 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  Rowid.**.** ^Eac
16970 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
16980 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
16990 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
169a0 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
169b0 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
169c0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
169d0 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
169e0 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
169f0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
16a00 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
16a10 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
16a20 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
16a30 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
16a40 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
16a50 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
16a60 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
16a70 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
16a80 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
16a90 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
16aa0 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
16ab0 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
16ac0 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
16ad0 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
16ae0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
16af0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
16b00 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
16b10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16b20 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
16b30 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
16b40 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
16b50 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a  owid] of the .**
16b60 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
16b70 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
16b80 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
16b90 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
16ba0 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
16bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16bc0 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20   D..** ^Inserts 
16bd0 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
16be0 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
16bf0 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a  not recorded..**
16c00 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
16c10 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
16c20 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a  o rowid tables.*
16c30 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
16c40 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61  rred on the data
16c50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16c60 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  D, .** then sqli
16c70 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
16c80 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
16c90 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   zero..**.** ^(I
16ca0 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
16cb0 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
16cc0 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
16cd0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
16ce0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
16cf0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
16d00 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
16d10 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
16d20 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
16d30 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
16d40 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
16d50 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
16d60 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
16d70 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
16d80 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
16d90 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
16da0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
16db0 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
16dc0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
16dd0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
16de0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
16df0 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
16e00 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
16e10 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
16e20 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
16e30 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
16e40 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
16e50 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
16e60 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
16e70 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
16e80 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
16e90 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
16ea0 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
16eb0 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
16ec0 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
16ed0 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
16ee0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
16ef0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
16f00 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
16f10 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
16f20 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
16f30 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
16f40 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
16f50 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
16f60 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
16f70 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
16f80 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
16f90 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
16fa0 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
16fb0 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
16fc0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
16fd0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
16fe0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
16ff0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
17000 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
17010 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
17020 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
17030 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
17040 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
17050 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
17060 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
17070 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
17080 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
17090 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
170a0 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
170b0 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
170c0 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
170d0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
170e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
170f0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
17100 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
17110 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
17120 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
17130 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
17140 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
17150 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
17160 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
17170 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
17180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
17190 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
171a0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
171b0 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
171c0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
171d0 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
171e0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
171f0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
17200 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
17210 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
17220 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17230 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
17240 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
17250 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
17260 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
17270 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
17280 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
17290 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
172a0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
172b0 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
172c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
172d0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
172e0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
172f0 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
17300 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
17310 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
17320 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
17330 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
17340 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
17350 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
17360 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
17370 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
17380 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
17390 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
173a0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
173b0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
173c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f  arameter..** ^(O
173d0 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
173e0 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
173f0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b  ecified by the [
17400 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
17410 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45  ],.** or [DELETE
17420 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  ] statement are 
17430 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
17440 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
17450 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
17460 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65  s or [foreign ke
17470 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e  y actions] are n
17480 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73  ot counted.)^ Us
17490 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
174a0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
174b0 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66  )] function to f
174c0 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
174d0 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a  mber of changes.
174e0 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  ** including cha
174f0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
17500 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65  riggers and fore
17510 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e  ign key actions.
17520 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  .**.** ^Changes 
17530 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
17540 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20  re simulated by 
17550 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
17560 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e  rigger].** are n
17570 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c  ot counted.  Onl
17580 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61  y real table cha
17590 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
175a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77  ..**.** ^(A "row
175b0 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68   change" is a ch
175c0 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
175d0 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
175e0 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
175f0 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
17600 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
17610 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
17620 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
17630 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
17640 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43  fects of [REPLAC
17650 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
17660 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c  solution,.** rol
17670 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f  lback, ABORT pro
17680 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54  cessing, [DROP T
17690 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79  ABLE], or by any
176a0 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e   other.** mechan
176b0 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  isms do not coun
176c0 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20  t as direct row 
176d0 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a  changes.)^.**.**
176e0 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
176f0 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
17700 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
17710 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
17720 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
17730 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54  ript of a [CREAT
17740 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17750 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53  ger]. .** Most S
17760 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
17770 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
17780 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
17790 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
177a0 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
177b0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
177c0 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
177d0 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
177e0 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
177f0 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
17800 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
17810 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
17820 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
17830 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
17840 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
17850 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
17860 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
17870 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  ** ^Calling [sql
17880 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
17890 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
178a0 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
178b0 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
178c0 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
178d0 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
178e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
178f0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
17900 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  f direct row cha
17910 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d  nges in the.** m
17920 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
17930 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
17940 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
17950 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
17960 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
17970 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20  t..**.** ^Thus, 
17980 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
17990 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
179a0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
179b0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
179c0 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
179d0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
179e0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
179f0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
17a00 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
17a10 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
17a20 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68  el.  ^(Within th
17a30 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
17a40 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
17a50 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
17a60 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
17a70 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
17a80 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
17a90 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
17aa0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
17ab0 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
17ac0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
17ad0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
17ae0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
17af0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
17b00 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
17b10 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
17b20 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
17b30 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
17b40 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
17b50 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
17b60 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
17b70 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ontext.)^.**.** 
17b80 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
17b90 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17ba0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
17bb0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
17bc0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
17bd0 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
17be0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
17bf0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
17c00 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
17c10 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
17c20 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
17c30 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
17c40 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
17c50 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
17c60 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
17c70 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
17c80 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
17c90 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
17ca0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
17cb0 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
17cc0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
17cd0 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
17ce0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
17cf0 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
17d00 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17d10 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
17d20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
17d30 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
17d40 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
17d50 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
17d60 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
17d70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17d80 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
17d90 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
17da0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
17db0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
17dc0 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
17dd0 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
17de0 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
17df0 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
17e00 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
17e10 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
17e20 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
17e30 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
17e40 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
17e50 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
17e60 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
17e70 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
17e80 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
17e90 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
17ea0 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
17eb0 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
17ec0 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
17ed0 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
17ee0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
17ef0 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
17f00 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
17f10 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
17f20 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
17f30 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
17f40 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
17f50 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
17f60 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
17f70 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
17f80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
17f90 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
17fa0 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
17fb0 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
17fc0 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
17fd0 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
17fe0 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
17ff0 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
18000 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
18010 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
18020 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
18030 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
18040 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
18050 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
18060 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
18070 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
18080 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
18090 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
180a0 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
180b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
180c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
180d0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
180e0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
180f0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
18100 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
18110 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
18120 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
18130 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
18140 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
18150 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
18160 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
18170 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
18180 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
18190 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
181a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
181b0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
181c0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
181d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
181e0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
181f0 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
18200 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
18210 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
18220 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
18230 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
18240 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
18250 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
18260 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
18270 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
18280 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
18290 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
182a0 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
182b0 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
182c0 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
182d0 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
182e0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
182f0 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
18300 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
18310 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
18320 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
18330 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
18340 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
18350 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
18360 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
18370 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
18380 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
18390 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
183a0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
183b0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
183c0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
183d0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
183e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
183f0 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
18400 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
18410 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
18420 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
18430 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
18440 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
18450 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
18460 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
18470 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
18480 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
18490 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
184a0 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
184b0 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
184c0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
184d0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
184e0 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
184f0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
18500 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
18510 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
18520 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
18530 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
18540 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
18550 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
18560 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
18570 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
18580 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
18590 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
185a0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
185b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
185c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
185d0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
185e0 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
185f0 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
18600 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
18610 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
18620 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
18630 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
18640 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
18650 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
18660 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
18670 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
18680 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
18690 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
186a0 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
186b0 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
186c0 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
186d0 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
186e0 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
186f0 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
18700 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18710 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
18720 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
18730 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
18740 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
18750 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
18760 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
18770 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
18780 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
18790 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
187a0 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
187b0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
187c0 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
187d0 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
187e0 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
187f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
18800 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
18810 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
18820 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
18830 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
18840 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
18850 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18860 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
18870 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
18880 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18890 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
188a0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
188b0 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
188c0 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
188d0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
188e0 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
188f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
18900 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18910 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
18920 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
18930 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
18940 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
18950 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
18960 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
18970 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
18980 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
18990 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
189a0 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
189b0 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
189c0 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
189d0 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
189e0 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
189f0 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
18a00 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
18a10 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
18a20 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
18a30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
18a40 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
18a50 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
18a60 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
18a70 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
18a80 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
18a90 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
18aa0 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
18ab0 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
18ac0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
18ad0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
18ae0 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
18af0 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
18b00 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
18b10 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
18b20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
18b30 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
18b40 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
18b50 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
18b60 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
18b70 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
18b80 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
18b90 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
18ba0 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
18bb0 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
18bc0 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
18bd0 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
18be0 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
18bf0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
18c00 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
18c10 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
18c20 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
18c30 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
18c40 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
18c50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
18c60 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
18c70 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
18c80 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
18c90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
18ca0 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
18cb0 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
18cc0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
18cd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
18ce0 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
18cf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
18d00 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
18d10 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
18d20 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
18d30 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
18d40 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
18d50 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
18d60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
18d70 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
18d80 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
18d90 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18da0 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
18db0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
18dc0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
18dd0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
18de0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18df0 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
18e00 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
18e10 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
18e20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
18e30 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
18e40 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
18e50 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
18e60 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
18e70 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
18e80 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
18e90 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
18ea0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
18eb0 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
18ec0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
18ed0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
18ee0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
18ef0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
18f00 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
18f10 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
18f20 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
18f30 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
18f40 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
18f50 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
18f60 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
18f70 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
18f80 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18f90 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
18fa0 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
18fb0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
18fc0 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
18fd0 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
18fe0 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54   Errors.**.** ^T
18ff0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
19000 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72  handler(D,X,P) r
19010 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
19020 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
19030 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20  X.** that might 
19040 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
19050 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
19060 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
19070 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  t is made to acc
19080 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74  ess a database t
19090 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20  able associated 
190a0 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  with.** [databas
190b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
190c0 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72  when another thr
190d0 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
190e0 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20  s has the table 
190f0 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73  locked..** The s
19100 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19110 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  ler() interface 
19120 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  is used to imple
19130 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ment.** [sqlite3
19140 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
19150 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73   and [PRAGMA bus
19160 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a  y_timeout]..**.*
19170 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
19180 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
19190 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
191a0 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
191b0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
191c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
191d0 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
191e0 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
191f0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
19200 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
19210 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
19220 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
19230 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
19240 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
19250 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
19260 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
19270 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19280 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
19290 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
192a0 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
192b0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
192c0 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
192d0 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
192e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
192f0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
19300 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
19310 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
19320 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
19330 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
19340 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
19350 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
19360 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
19370 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
19380 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
19390 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
193a0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
193b0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
193c0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
193d0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
193e0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
193f0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
19400 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
19410 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
19420 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
19430 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
19440 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
19450 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
19460 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
19470 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
19480 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
19490 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
194a0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
194b0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
194c0 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
194d0 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
194e0 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
194f0 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
19500 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
19510 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
19520 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
19530 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
19540 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
19550 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
19560 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
19570 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
19580 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
19590 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
195a0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
195b0 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
195c0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
195d0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
195e0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
195f0 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
19600 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
19610 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
19620 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
19630 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
19640 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
19650 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
19660 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
19670 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
19680 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
19690 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
196a0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
196b0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
196c0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
196d0 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
196e0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
196f0 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
19700 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
19710 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
19720 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
19730 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
19740 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
19750 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
19760 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
19770 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
19780 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
19790 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
197a0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
197b0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
197c0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
197d0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
197e0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
197f0 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
19800 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
19810 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
19820 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
19830 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
19840 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
19850 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
19860 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
19870 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
19880 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  LL..**.** ^The [
19890 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
198a0 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
198b0 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
198c0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
198d0 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
198e0 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
198f0 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
19900 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
19910 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
19920 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
19930 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
19940 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
19950 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
19960 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
19970 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
19980 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
19990 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
199a0 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
199b0 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
199c0 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
199d0 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
199e0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
199f0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
19a00 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
19a10 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20  eaders.  ^If it 
19a20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
19a30 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
19a40 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
19a50 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
19a60 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
19a70 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
19a80 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
19a90 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
19aa0 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
19ab0 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
19ac0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
19ad0 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
19ae0 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
19af0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54  RR_BLOCKED].  ^T
19b00 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
19b10 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
19b20 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
19b30 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
19b40 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
19b50 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
19b60 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
19b70 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
19b80 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
19b90 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
19ba0 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
19bb0 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
19bc0 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
19bd0 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
19be0 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  portant..**.** ^
19bf0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
19c00 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
19c10 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
19c20 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
19c30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19c40 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
19c50 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
19c60 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
19c70 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
19c80 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
19c90 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
19ca0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
19cb0 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
19cc0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
19cd0 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
19ce0 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
19cf0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
19d00 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
19d10 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
19d20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
19d30 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
19d40 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
19d50 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
19d60 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
19d70 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
19d80 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
19d90 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
19da0 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
19db0 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
19dc0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
19dd0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
19de0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
19df0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
19e00 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
19e10 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
19e20 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
19e30 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
19e40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
19e50 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
19e60 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
19e70 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
19e80 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
19e90 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
19ea0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
19eb0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
19ec0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
19ed0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
19ee0 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
19ef0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
19f00 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
19f10 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
19f20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
19f30 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
19f40 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
19f50 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
19f60 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
19f70 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
19f80 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
19f90 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
19fa0 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
19fb0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
19fc0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
19fd0 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
19fe0 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
19ff0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1a000 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1a010 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
1a020 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
1a030 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
1a040 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
1a050 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
1a060 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
1a070 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
1a080 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1a090 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1a0a0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1a0b0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1a0c0 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1a0d0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1a0e0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1a0f0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1a100 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1a110 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1a120 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1a130 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a140 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
1a150 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
1a160 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1a170 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
1a180 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
1a190 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
1a1a0 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
1a1b0 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
1a1c0 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
1a1d0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
1a1e0 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  leared.)^.**.** 
1a1f0 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47  See also:  [PRAG
1a200 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
1a210 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1a220 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
1a230 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
1a240 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a250 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
1a260 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
1a270 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
1a280 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
1a290 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1a2a0 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
1a2b0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1a2c0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
1a2d0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1a2e0 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
1a2f0 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
1a300 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
1a310 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
1a320 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
1a330 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
1a340 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
1a350 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1a360 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
1a370 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
1a380 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
1a390 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
1a3a0 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
1a3b0 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
1a3c0 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
1a3d0 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
1a3e0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
1a3f0 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
1a400 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
1a410 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
1a420 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1a430 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
1a440 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
1a450 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
1a460 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
1a470 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1a480 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
1a490 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1a4a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
1a4b0 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
1a4c0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
1a4d0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1a4e0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1a4f0 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
1a500 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
1a510 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
1a520 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
1a530 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
1a540 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a550 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
1a560 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
1a570 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
1a580 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
1a590 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
1a5a0 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
1a5b0 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
1a5c0 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
1a5d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
1a5e0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
1a5f0 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
1a600 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1a610 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
1a620 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
1a630 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1a640 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1a650 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
1a660 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
1a670 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
1a680 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
1a690 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
1a6a0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1a6b0 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
1a6c0 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
1a6d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1a6e0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
1a6f0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
1a700 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
1a710 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1a720 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
1a730 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
1a740 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a750 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
1a760 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
1a770 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
1a780 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1a790 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1a7a0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
1a7b0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
1a7c0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
1a7d0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
1a7e0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
1a7f0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
1a800 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
1a810 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
1a820 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
1a830 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1a840 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
1a850 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
1a860 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
1a870 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
1a880 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
1a890 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
1a8a0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
1a8b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1a8c0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
1a8d0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
1a8e0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
1a8f0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
1a900 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
1a910 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1a920 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a930 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
1a940 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
1a950 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
1a960 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
1a970 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
1a980 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
1a990 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a9a0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
1a9b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a9c0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
1a9d0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a9e0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
1a9f0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
1aa00 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
1aa10 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
1aa20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1aa30 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
1aa40 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1aa50 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1aa60 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1aa70 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
1aa80 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
1aa90 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
1aaa0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
1aab0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
1aac0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1aad0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
1aae0 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
1aaf0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
1ab00 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
1ab10 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
1ab20 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
1ab30 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
1ab40 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
1ab50 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
1ab60 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
1ab70 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
1ab80 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
1ab90 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
1aba0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1abb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
1abc0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1abd0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
1abe0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1abf0 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
1ac00 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
1ac10 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
1ac20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ac30 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
1ac40 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
1ac50 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
1ac60 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
1ac70 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
1ac80 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
1ac90 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
1aca0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
1acb0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
1acc0 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
1acd0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
1ace0 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
1acf0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
1ad00 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1ad10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
1ad20 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
1ad30 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
1ad40 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1ad50 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
1ad60 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
1ad70 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
1ad80 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
1ad90 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
1ada0 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
1adb0 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
1adc0 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
1add0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
1ade0 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
1adf0 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
1ae00 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
1ae10 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
1ae20 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
1ae30 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
1ae40 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1ae50 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
1ae60 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
1ae70 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1ae80 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
1ae90 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
1aea0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
1aeb0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
1aec0 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1aed0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1aee0 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1aef0 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1af00 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1af10 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1af20 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1af30 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1af40 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1af50 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1af60 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1af70 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1af80 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1af90 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1afa0 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1afb0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1afc0 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1afd0 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1afe0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1aff0 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1b000 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1b010 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
1b020 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1b030 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1b040 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b050 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1b060 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1b070 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1b080 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1b090 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1b0a0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1b0b0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1b0c0 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1b0d0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1b0e0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1b0f0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1b100 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1b110 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1b120 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1b130 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1b140 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1b150 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b160 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1b170 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1b180 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1b190 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1b1a0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1b1b0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1b1c0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1b1d0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1b1e0 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1b1f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
1b200 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1b210 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1b220 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1b230 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1b240 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1b250 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b260 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1b270 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1b280 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1b290 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1b2a0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1b2b0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1b2c0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1b2d0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1b2e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1b2f0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1b300 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1b310 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1b320 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1b330 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1b340 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1b350 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1b360 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1b370 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1b380 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1b390 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1b3a0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1b3b0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1b3c0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1b3d0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1b3e0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1b3f0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1b400 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1b410 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1b420 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1b430 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1b440 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1b450 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1b460 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1b470 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1b480 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1b490 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1b4a0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1b4b0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1b4c0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1b4d0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1b4e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1b4f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1b500 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1b510 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1b520 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1b530 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1b540 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1b550 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1b560 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1b570 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1b580 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1b590 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1b5a0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1b5b0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1b5c0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1b5d0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1b5e0 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1b5f0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
1b600 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1b610 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
1b620 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
1b630 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
1b640 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
1b650 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
1b660 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
1b670 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1b680 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1b690 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
1b6a0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1b6b0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
1b6c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
1b6d0 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
1b6e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
1b6f0 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
1b700 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
1b710 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
1b720 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1b730 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
1b740 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
1b750 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1b760 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
1b770 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
1b780 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
1b790 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
1b7a0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1b7b0 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1b7c0 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1b7d0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1b7e0 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1b7f0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1b800 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1b810 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1b820 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1b830 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1b840 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1b850 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1b860 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1b870 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1b880 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1b890 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1b8a0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1b8b0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1b8c0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1b8d0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1b8e0 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1b8f0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1b900 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1b910 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1b920 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1b930 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b940 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1b950 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1b960 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1b970 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b980 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1b990 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1b9a0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1b9b0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1b9c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1b9d0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1b9e0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1b9f0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1ba00 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1ba10 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1ba20 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1ba30 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1ba40 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1ba50 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1ba60 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1ba70 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1ba80 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1ba90 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1baa0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1bab0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1bac0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1bad0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1bae0 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1baf0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1bb00 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1bb10 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1bb20 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1bb30 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1bb40 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1bb50 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1bb60 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1bb70 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1bb80 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1bb90 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1bba0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1bbb0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1bbc0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1bbd0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1bbe0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1bbf0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1bc00 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1bc10 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1bc20 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1bc30 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1bc40 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1bc50 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1bc60 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1bc70 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1bc80 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1bc90 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1bca0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1bcb0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1bcc0 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1bcd0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1bce0 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1bcf0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1bd00 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1bd10 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1bd20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1bd30 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1bd40 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1bd50 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1bd60 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1bd70 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1bd80 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1bd90 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1bda0 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1bdb0 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1bdc0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1bdd0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1bde0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1bdf0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1be00 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1be10 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1be20 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1be30 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1be40 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1be50 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1be60 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1be70 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1be80 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1be90 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1bea0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1beb0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1bec0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1bed0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1bee0 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1bef0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1bf00 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1bf10 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
1bf20 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
1bf30 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
1bf40 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
1bf50 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
1bf60 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
1bf70 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
1bf80 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
1bf90 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
1bfa0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
1bfb0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
1bfc0 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63  t string.)^.*/.c
1bfd0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
1bfe0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1bff0 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
1c000 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
1c010 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1c020 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
1c030 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
1c040 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1c050 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  *, ...);.char *s
1c060 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1c070 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1c080 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1c090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c0a0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1c0b0 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
1c0c0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
1c0d0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
1c0e0 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
1c0f0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
1c100 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
1c110 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c120 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
1c130 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
1c140 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
1c150 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
1c160 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
1c170 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
1c180 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
1c190 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
1c1a0 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
1c1b0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
1c1c0 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
1c1d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1c1e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
1c1f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
1c200 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
1c210 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
1c220 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1c230 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
1c240 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
1c250 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
1c260 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1c270 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
1c280 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
1c290 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
1c2a0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1c2b0 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
1c2c0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
1c2d0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1c2e0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
1c2f0 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
1c300 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
1c310 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
1c320 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1c330 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
1c340 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
1c350 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
1c360 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1c370 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c380 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1c390 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
1c3a0 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
1c3b0 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
1c3c0 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
1c3d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
1c3e0 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
1c3f0 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
1c400 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1c410 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
1c420 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1c430 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
1c440 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
1c450 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
1c460 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
1c470 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
1c480 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
1c490 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
1c4a0 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
1c4b0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
1c4c0 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
1c4d0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1c4e0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1c4f0 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
1c500 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
1c510 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1c520 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
1c530 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
1c540 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
1c550 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
1c560 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
1c570 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
1c580 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
1c590 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1c5a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1c5b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c5c0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  )..**.** ^(The s
1c5d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c5e0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1c5f0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1c600 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1c610 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
1c620 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1c630 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
1c640 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1c650 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
1c660 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1c670 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
1c680 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1c690 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68  meter.)^ ^ If th
1c6a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1c6b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1c6c0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
1c6d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1c6e0 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
1c6f0 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
1c700 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1c710 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
1c720 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
1c730 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c740 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1c750 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
1c760 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1c770 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c780 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1c790 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1c7a0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1c7b0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1c7c0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1c7d0 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
1c7e0 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
1c7f0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
1c800 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c810 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1c820 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1c830 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1c840 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c850 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1c860 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1c870 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
1c880 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1c890 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
1c8a0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1c8b0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1c8c0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1c8d0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1c8e0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1c8f0 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1c900 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1c910 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1c920 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1c930 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c940 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
1c950 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1c960 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1c970 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1c980 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
1c990 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
1c9a0 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
1c9b0 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
1c9c0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1c9d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1c9e0 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
1c9f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
1ca00 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1ca10 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1ca20 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1ca30 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1ca40 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1ca50 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1ca60 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1ca70 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1ca80 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1ca90 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1caa0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1cab0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1cac0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1cad0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1cae0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1caf0 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1cb00 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1cb10 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1cb20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1cb30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1cb40 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1cb50 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1cb60 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1cb70 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1cb80 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1cb90 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1cba0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1cbb0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1cbc0 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1cbd0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1cbe0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1cbf0 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1cc00 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1cc10 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1cc20 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1cc30 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1cc40 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1cc50 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1cc60 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1cc70 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1cc80 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1cc90 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1cca0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1ccb0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1ccc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1ccd0 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1cce0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1ccf0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1cd00 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1cd10 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1cd20 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1cd30 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1cd40 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1cd50 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1cd60 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1cd70 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1cd80 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1cd90 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1cda0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1cdb0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1cdc0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1cdd0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1cde0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1cdf0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1ce00 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1ce10 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1ce20 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1ce30 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1ce40 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1ce50 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1ce60 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1ce70 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1ce80 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1ce90 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1cea0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1ceb0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1cec0 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
1ced0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1cee0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1cef0 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1cf00 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
1cf10 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1cf20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1cf30 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1cf40 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1cf50 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1cf60 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1cf70 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1cf80 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1cf90 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1cfa0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1cfb0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1cfc0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1cfd0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1cfe0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1cff0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1d000 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1d010 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1d020 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1d030 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1d040 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1d050 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1d060 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1d070 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1d080 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1d090 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1d0a0 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1d0b0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d0c0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1d0d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1d0e0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1d0f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d100 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1d110 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1d120 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1d130 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1d140 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1d150 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1d160 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1d170 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1d180 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1d190 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1d1a0 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1d1b0 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1d1c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1d1d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1d1e0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1d1f0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1d200 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1d210 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1d220 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1d230 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d240 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1d250 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1d260 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1d270 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1d280 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1d290 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1d2a0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1d2b0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1d2c0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1d2d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1d2e0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1d2f0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1d300 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1d310 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1d320 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1d330 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1d340 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1d350 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
1d360 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1d370 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1d380 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
1d390 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1d3a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1d3b0 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1d3c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1d3d0 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1d3e0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1d3f0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1d400 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1d410 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1d420 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1d430 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1d440 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1d450 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1d460 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1d470 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1d480 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1d490 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1d4a0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1d4b0 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1d4c0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1d4d0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1d4e0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1d4f0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1d500 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1d510 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1d520 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1d530 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1d540 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1d550 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1d560 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1d570 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1d580 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1d590 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1d5a0 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1d5b0 2a 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20  * ^If N is less 
1d5c0 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 50  than one, then P
1d5d0 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
1d5e0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
1d5f0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
1d600 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
1d610 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
1d620 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
1d630 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
1d640 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68  ess than one, th
1d650 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  en the PRNG is s
1d660 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
1d670 6f 6d 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69 6e  omness.** obtain
1d680 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
1d690 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1d6a0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
1d6b0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1d6c0 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  ct..** ^If the p
1d6d0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
1d6e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64  this routine had
1d6f0 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f   an N of 1 or mo
1d700 72 65 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 70  re then.** the p
1d710 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
1d720 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
1d730 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
1d740 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
1d750 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1d760 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
1d770 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
1d780 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
1d790 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
1d7a0 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
1d7b0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1d7c0 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
1d7d0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
1d7e0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1d7f0 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1d800 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d810 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1d820 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1d830 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1d840 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1d850 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1d860 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1d870 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1d880 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1d890 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1d8a0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1d8b0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1d8c0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1d8d0 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1d8e0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1d8f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d900 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1d910 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1d920 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1d930 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1d940 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
1d950 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
1d960 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
1d970 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
1d980 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
1d990 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
1d9a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1d9b0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
1d9c0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
1d9d0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
1d9e0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1d9f0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1da00 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1da10 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
1da20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
1da30 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
1da40 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
1da50 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
1da60 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
1da70 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
1da80 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
1da90 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
1daa0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
1dab0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
1dac0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1dad0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
1dae0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
1daf0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
1db00 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
1db10 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
1db20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1db30 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
1db40 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
1db50 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
1db60 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
1db70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1db80 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1db90 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
1dba0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1dbb0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1dbc0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1dbd0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1dbe0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1dbf0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
1dc00 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
1dc10 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
1dc20 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
1dc30 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1dc40 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1dc50 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
1dc60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1dc70 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1dc80 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1dc90 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
1dca0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1dcb0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1dcc0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
1dcd0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
1dce0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
1dcf0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1dd00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1dd10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1dd20 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
1dd30 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
1dd40 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1dd50 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1dd60 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1dd70 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1dd80 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1dd90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1dda0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1ddb0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1ddc0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1ddd0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1dde0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1ddf0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1de00 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1de10 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1de20 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1de30 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1de40 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1de50 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1de60 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1de70 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1de80 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1de90 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1dea0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1deb0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1dec0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1ded0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1dee0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1def0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1df00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1df10 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
1df20 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
1df30 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
1df40 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1df50 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1df60 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1df70 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
1df80 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
1df90 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
1dfa0 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
1dfb0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
1dfc0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
1dfd0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
1dfe0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
1dff0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
1e000 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
1e010 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
1e020 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1e030 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
1e040 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1e050 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
1e060 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1e070 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
1e080 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
1e090 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
1e0a0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
1e0b0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
1e0c0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
1e0d0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
1e0e0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
1e0f0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
1e100 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
1e110 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1e120 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
1e130 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
1e140 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1e150 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
1e160 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1e170 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
1e180 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
1e190 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
1e1a0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
1e1b0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
1e1c0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
1e1d0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
1e1e0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
1e1f0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
1e200 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
1e210 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
1e220 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
1e230 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
1e240 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
1e250 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
1e260 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
1e270 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
1e280 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
1e290 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
1e2a0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
1e2b0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
1e2c0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
1e2d0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
1e2e0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
1e2f0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
1e300 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
1e310 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
1e320 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
1e330 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1e340 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
1e350 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
1e360 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
1e370 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1e380 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
1e390 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
1e3a0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
1e3b0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
1e3c0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
1e3d0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
1e3e0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
1e3f0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
1e400 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1e410 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
1e420 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
1e430 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
1e440 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
1e450 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
1e460 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
1e470 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
1e480 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
1e490 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
1e4a0 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
1e4b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e4c0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
1e4d0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
1e4e0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e4f0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
1e500 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
1e510 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
1e520 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
1e530 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
1e540 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
1e550 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1e560 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1e570 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
1e580 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e590 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1e5a0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1e5b0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1e5c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1e5d0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1e5e0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
1e5f0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
1e600 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1e610 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1e620 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1e630 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1e640 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1e650 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1e660 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1e670 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1e680 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1e690 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
1e6a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e6b0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
1e6c0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1e6d0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
1e6e0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
1e6f0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
1e700 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1e710 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
1e720 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
1e730 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
1e740 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
1e750 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
1e760 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
1e770 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
1e780 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
1e790 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
1e7a0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
1e7b0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
1e7c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e7d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
1e7e0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
1e7f0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1e800 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1e810 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
1e820 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
1e830 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
1e840 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
1e850 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
1e860 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
1e870 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
1e880 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1e890 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
1e8a0 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
1e8b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e8c0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
1e8d0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
1e8e0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1e8f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1e900 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1e910 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1e920 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1e930 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1e940 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1e950 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1e960 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1e970 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1e980 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1e990 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1e9a0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1e9b0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1e9c0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1e9d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1e9e0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1e9f0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1ea00 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1ea10 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1ea20 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1ea30 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1ea40 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1ea50 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1ea60 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1ea70 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1ea80 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1ea90 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1eaa0 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1eab0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1eac0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1ead0 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1eae0 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1eaf0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c  o used as a [SQL
1eb00 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
1eb10 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66  eturn code].** f
1eb20 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1eb30 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1eb40 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1eb50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1eb60 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1eb70 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1eb80 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1eb90 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1eba0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1ebb0 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1ebc0 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1ebd0 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1ebe0 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1ebf0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1ec00 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1ec10 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1ec20 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1ec30 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1ec40 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1ec50 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1ec60 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1ec70 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1ec80 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1ec90 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1eca0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1ecb0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1ecc0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1ecd0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1ece0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1ecf0 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1ed00 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1ed10 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1ed20 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1ed30 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1ed40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ed50 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1ed60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1ed70 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1ed80 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1ed90 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1eda0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1edb0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1edc0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1edd0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1ede0 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1edf0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1ee00 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1ee10 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1ee20 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1ee30 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1ee40 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1ee50 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1ee60 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1ee70 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1ee80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ee90 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1eea0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1eeb0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1eec0 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1eed0 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1eee0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1eef0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ef00 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1ef10 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1ef20 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1ef30 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1ef40 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1ef50 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1ef60 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1ef70 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1ef80 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1ef90 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1efa0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1efb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1efc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1efd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1efe0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1eff0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1f000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1f010 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1f020 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1f030 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1f040 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f050 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1f060 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1f070 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1f080 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f090 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f0a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f0b0 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1f0c0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1f0d0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1f0e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f0f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f100 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1f110 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1f120 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f130 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f140 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f150 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1f160 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1f170 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1f180 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f190 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1f1a0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1f1b0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1f1c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f1d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f1e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1f1f0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1f200 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1f210 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f220 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f230 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1f240 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1f250 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1f260 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f270 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f280 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1f290 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1f2a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f2b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f2c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f2d0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1f2e0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1f2f0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f300 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f310 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f320 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1f330 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1f340 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f350 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f370 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1f380 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1f390 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1f3a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f3b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f3c0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1f3d0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1f3e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1f3f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f410 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1f420 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1f430 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1f440 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f460 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1f470 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1f480 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1f490 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f4a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f4b0 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1f4c0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1f4d0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1f4e0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f4f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f500 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1f510 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1f520 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1f530 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f540 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1f550 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1f560 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1f570 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f580 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f590 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1f5a0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1f5b0 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1f5c0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1f5d0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1f5e0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1f5f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f600 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1f610 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1f620 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1f630 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1f640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1f650 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1f660 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f670 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f680 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1f690 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1f6a0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1f6b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f6c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f6d0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1f6e0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1f6f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f700 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1f710 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f720 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1f730 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1f740 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1f750 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f760 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f770 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1f780 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1f790 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1f7a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f7b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f7c0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1f7d0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1f7e0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1f7f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f810 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1f820 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1f830 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f840 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f860 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1f870 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1f880 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f890 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f8a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f8b0 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1f8c0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1f8d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f8e0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f8f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f900 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1f910 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1f920 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1f930 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1f940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1f950 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1f960 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1f970 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1f980 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1f990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1f9a0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1f9b0 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1f9c0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1f9d0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1f9e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1f9f0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1fa00 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1fa10 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
1fa20 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
1fa30 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
1fa40 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
1fa50 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1fa60 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
1fa70 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
1fa80 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
1fa90 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1faa0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1fab0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1fac0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
1fad0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
1fae0 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
1faf0 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
1fb00 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
1fb10 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1fb20 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1fb30 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1fb40 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1fb50 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1fb60 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1fb70 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1fb80 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1fb90 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1fba0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1fbb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
1fbc0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
1fbd0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
1fbe0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
1fbf0 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
1fc00 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
1fc10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
1fc20 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
1fc30 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
1fc40 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
1fc50 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
1fc60 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
1fc70 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
1fc80 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
1fc90 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
1fca0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
1fcb0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
1fcc0 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
1fcd0 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
1fce0 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
1fcf0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  )^.**.** The [SQ
1fd00 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
1fd10 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
1fd20 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ime option can b
1fd30 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a  e used to limit.
1fd40 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  ** the length of
1fd50 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
1fd60 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20  r] expansion in 
1fd70 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71  the output of sq
1fd80 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a  lite3_trace()..*
1fd90 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1fda0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1fdb0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1fdc0 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1fdd0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1fde0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1fdf0 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
1fe00 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1fe10 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
1fe20 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1fe30 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
1fe40 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
1fe50 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
1fe60 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
1fe70 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
1fe80 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
1fe90 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
1fea0 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
1feb0 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
1fec0 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
1fed0 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
1fee0 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
1fef0 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
1ff00 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
1ff10 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
1ff20 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
1ff30 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
1ff40 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
1ff50 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
1ff60 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1ff70 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
1ff80 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
1ff90 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
1ffa0 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
1ffb0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
1ffc0 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
1ffd0 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
1ffe0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1fff0 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
20000 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
20010 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
20020 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  QLite..*/.void *
20030 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
20040 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
20050 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
20060 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
20070 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
20080 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
20090 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
200a0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
200b0 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
200c0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
200d0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
200e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
200f0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
20100 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
20110 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20120 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
20130 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
20140 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
20150 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
20160 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
20170 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
20180 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
20190 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
201a0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
201b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
201c0 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
201d0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
201e0 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
201f0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
20200 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
20210 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
20220 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
20230 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
20240 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
20250 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
20260 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
20270 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
20280 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
20290 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
202a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
202b0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
202c0 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78   N is the approx
202d0 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20  imate number of 
202e0 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
202f0 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
20300 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
20310 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
20320 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
20330 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
20340 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20  allback X.  ^If 
20350 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
20360 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  ne then the prog
20370 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  ress.** handler 
20380 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
20390 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
203a0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
203b0 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
203c0 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
203d0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
203e0 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
203f0 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
20400 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
20410 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
20420 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
20430 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
20440 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
20450 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
20460 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
20470 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
20480 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
20490 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
204a0 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
204b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
204c0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
204d0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
204e0 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
204f0 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
20500 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
20510 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
20520 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
20530 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
20540 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
20550 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
20560 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
20570 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
20580 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
20590 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
205a0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
205b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
205c0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
205d0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
205e0 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
205f0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
20600 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
20610 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
20620 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
20630 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
20640 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
20650 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
20660 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
20670 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76  ragraph..**.*/.v
20680 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
20690 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
206a0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
206b0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
206c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
206d0 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
206e0 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
206f0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
20700 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
20710 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
20720 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
20730 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
20740 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
20750 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
20760 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
20770 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
20780 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
20790 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
207a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
207b0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
207c0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
207d0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
207e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
207f0 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
20800 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
20810 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
20820 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
20830 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
20840 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
20850 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
20860 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
20870 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
20880 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
20890 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
208a0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
208b0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
208c0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
208d0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
208e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
208f0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
20900 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
20910 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20920 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
20930 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
20940 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
20950 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
20960 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
20970 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
20980 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
20990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
209a0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
209b0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
209c0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
209d0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
209e0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
209f0 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
20a00 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
20a10 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
20a20 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
20a30 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
20a40 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
20a50 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
20a60 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
20a70 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
20a80 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
20a90 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
20aa0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20ab0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
20ac0 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
20ad0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
20ae0 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
20af0 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
20b00 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
20b10 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
20b20 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
20b30 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
20b40 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
20b50 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
20b60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
20b70 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
20b80 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
20b90 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
20ba0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
20bb0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
20bc0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
20bd0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
20be0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
20bf0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
20c00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
20c10 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
20c20 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
20c30 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
20c40 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
20c50 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
20c60 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
20c70 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
20c80 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
20c90 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
20ca0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
20cb0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
20cc0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
20cd0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
20ce0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
20cf0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
20d00 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
20d10 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
20d20 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
20d30 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
20d40 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
20d50 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
20d60 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
20d70 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
20d80 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
20d90 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
20da0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
20db0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
20dc0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
20dd0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
20de0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
20df0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
20e00 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
20e10 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
20e20 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
20e30 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
20e40 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
20e50 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
20e60 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
20e70 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
20e80 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
20e90 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
20ea0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
20eb0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
20ec0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
20ed0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
20ee0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
20ef0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
20f00 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
20f10 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
20f20 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
20f30 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
20f40 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
20f50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20f60 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
20f70 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
20f80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
20f90 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20fa0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
20fb0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
20fc0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
20fd0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
20fe0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
20ff0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
21000 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
21010 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
21020 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
21030 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
21040 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
21050 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
21060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
21070 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
21080 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
21090 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
210a0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
210b0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
210c0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
210d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
210e0 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
210f0 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
21100 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
21110 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
21120 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
21130 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
21140 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
21150 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
21160 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
21170 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
21180 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
21190 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
211a0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
211b0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
211c0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
211d0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
211e0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
211f0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
21200 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
21210 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
21220 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
21230 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
21240 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
21250 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
21260 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
21270 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
21280 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
21290 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
212a0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
212b0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
212c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
212d0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
212e0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
212f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
21300 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
21310 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
21320 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
21330 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
21340 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
21350 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
21360 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
21370 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
21380 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
21390 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
213a0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
213b0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
213c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
213d0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
213e0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
213f0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
21400 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
21410 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
21420 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
21430 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
21440 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
21450 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
21460 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
21470 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
21480 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
21490 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
214a0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
214b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
214c0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
214d0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
214e0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
214f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
21500 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
21510 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
21520 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
21530 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
21540 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
21550 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
21560 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
21570 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
21580 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
21590 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
215a0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
215b0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
215c0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
215d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
215e0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
215f0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
21600 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
21610 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
21620 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
21630 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
21640 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
21650 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
21660 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
21670 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
21680 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
21690 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
216a0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
216b0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
216c0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
216d0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
216e0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
216f0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
21700 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
21710 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
21720 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
21730 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
21740 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
21750 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
21760 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
21770 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
21780 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
21790 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
217a0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
217b0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
217c0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
217d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
217e0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
217f0 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
21800 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
21810 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
21820 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
21830 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
21840 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
21850 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
21860 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
21870 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
21880 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
21890 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
218a0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
218b0 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
218c0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
218d0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
218e0 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
218f0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
21900 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
21910 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
21920 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
21930 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
21940 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
21950 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
21960 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
21970 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
21980 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
21990 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
219a0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
219b0 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
219c0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
219d0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
219e0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
219f0 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
21a00 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
21a10 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
21a20 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
21a30 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
21a40 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
21a50 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
21a60 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
21a70 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
21a80 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
21a90 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
21aa0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
21ab0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
21ac0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
21ad0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
21ae0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
21af0 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
21b00 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
21b10 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
21b20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
21b30 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
21b40 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
21b50 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
21b60 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
21b70 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
21b80 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
21b90 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
21ba0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
21bb0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
21bc0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
21bd0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
21be0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
21bf0 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
21c00 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
21c10 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
21c20 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
21c30 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
21c40 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
21c50 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
21c60 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
21c70 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
21c80 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
21c90 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
21ca0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
21cb0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
21cc0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
21cd0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
21ce0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
21cf0 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
21d00 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
21d10 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
21d20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
21d30 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
21d40 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
21d50 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
21d60 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77  . .** ^On window
21d70 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
21d80 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
21d90 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
21da0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
21db0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
21dc0 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  :")..**.** [[cor
21dd0 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
21de0 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
21df0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
21e00 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
21e10 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
21e20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
21e30 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
21e40 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
21e50 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
21e60 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
21e70 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
21e80 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
21e90 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
21ea0 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d  hree query param
21eb0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
21ec0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
21ed0 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
21ee0 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
21ef0 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
21f00 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
21f10 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
21f20 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
21f30 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
21f40 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
21f50 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
21f60 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
21f70 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
21f80 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
21f90 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
21fa0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
21fb0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
21fc0 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
21fd0 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
21fe0 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
21ff0 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
22000 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
22010 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
22020 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
22030 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
22040 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
22050 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
22060 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
22070 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
22080 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
22090 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
220a0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
220b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
220c0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
220d0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
220e0 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
220f0 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
22100 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
22110 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
22120 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
22130 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
22140 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
22150 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
22160 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
22170 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
22180 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
22190 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
221a0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
221b0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
221c0 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
221d0 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
221e0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
221f0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
22200 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
22210 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
22220 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
22230 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22240 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
22250 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
22260 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
22270 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
22280 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
22290 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
222a0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
222b0 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
222c0 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
222d0 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
222e0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
222f0 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
22300 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
22310 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
22320 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
22330 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
22340 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
22350 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
22360 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
22370 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
22380 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
22390 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
223a0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
223b0 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
223c0 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
223d0 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
223e0 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
223f0 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
22400 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
22410 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
22420 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
22430 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
22440 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
22450 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
22460 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
22470 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
22480 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
22490 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
224a0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
224b0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
224c0 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
224d0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
224e0 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
224f0 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
22500 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
22510 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
22520 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
22530 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
22540 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
22550 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
22560 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
22570 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
22580 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
22590 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
225a0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
225b0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
225c0 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
225d0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
225e0 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
225f0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
22600 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
22610 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
22620 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
22630 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
22640 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
22650 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
22660 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
22670 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
22680 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
22690 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
226a0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
226b0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
226c0 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
226d0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
226e0 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
226f0 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
22700 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
22710 20 6d 61 79 20 62 65 20 22 74 72 75 65 22 20 28   may be "true" (
22720 6f 72 20 22 6f 6e 22 20 6f 72 20 22 79 65 73 22  or "on" or "yes"
22730 20 6f 72 0a 2a 2a 20 20 20 20 20 22 31 22 29 20   or.**     "1") 
22740 6f 72 20 22 66 61 6c 73 65 22 20 28 6f 72 20 22  or "false" (or "
22750 6f 66 66 22 20 6f 72 20 22 6e 6f 22 20 6f 72 20  off" or "no" or 
22760 22 30 22 29 20 74 6f 20 69 6e 64 69 63 61 74 65  "0") to indicate
22770 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
22780 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72   [powersafe over
22790 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20  write] property 
227a0 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74  does or does not
227b0 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a   apply to the.**
227c0 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64       storage med
227d0 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  ia on which the 
227e0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65  database file re
227f0 73 69 64 65 73 2e 20 20 5e 54 68 65 20 70 73 6f  sides.  ^The pso
22800 77 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  w query.**     p
22810 61 72 61 6d 65 74 65 72 20 6f 6e 6c 79 20 77 6f  arameter only wo
22820 72 6b 73 20 66 6f 72 20 74 68 65 20 62 75 69 6c  rks for the buil
22830 74 2d 69 6e 20 75 6e 69 78 20 61 6e 64 20 57 69  t-in unix and Wi
22840 6e 64 6f 77 73 20 56 46 53 65 73 2e 0a 2a 2a 0a  ndows VFSes..**.
22850 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
22860 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
22870 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
22880 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
22890 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
228a0 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
228b0 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
228c0 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
228d0 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
228e0 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
228f0 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
22900 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
22910 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
22920 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
22930 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
22940 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
22950 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
22960 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
22970 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
22980 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
22990 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
229a0 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
229b0 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
229c0 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
229d0 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
229e0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
229f0 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
22a00 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
22a10 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
22a20 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
22a30 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
22a40 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
22a50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22a60 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
22a70 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
22a80 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
22a90 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
22aa0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
22ab0 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
22ac0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
22ad0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
22ae0 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
22af0 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
22b00 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
22b10 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
22b20 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
22b30 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
22b40 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
22b50 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
22b60 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
22b70 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
22b80 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
22b90 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
22ba0 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
22bb0 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
22bc0 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
22bd0 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
22be0 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
22bf0 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
22c00 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
22c10 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
22c20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
22c30 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
22c40 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
22c50 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
22c60 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
22c70 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
22c80 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
22c90 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
22ca0 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
22cb0 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
22cc0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
22cd0 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
22ce0 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
22cf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
22d00 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
22d10 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
22d20 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
22d30 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
22d40 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
22d50 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
22d60 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
22d70 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
22d80 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
22d90 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
22da0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
22db0 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
22dc0 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
22dd0 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
22de0 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
22df0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
22e00 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
22e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
22e20 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
22e30 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
22e40 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
22e50 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
22e60 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
22e70 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
22e80 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
22e90 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
22ea0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
22eb0 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
22ec0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22ed0 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
22ee0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
22ef0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
22f00 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
22f10 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
22f20 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
22f30 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
22f40 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
22f50 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
22f60 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
22f70 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
22f80 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
22f90 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
22fa0 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
22fb0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
22fc0 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
22fd0 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
22fe0 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
22ff0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
23000 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
23010 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
23020 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
23030 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
23040 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
23050 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
23060 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
23070 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
23080 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
23090 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
230a0 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
230b0 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
230c0 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
230d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
230e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
230f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23100 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
23110 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
23120 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23130 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
23140 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
23150 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
23160 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
23170 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
23180 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
23190 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
231a0 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
231b0 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
231c0 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
231d0 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
231e0 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
231f0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
23200 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
23210 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
23220 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23230 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
23240 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
23250 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
23260 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
23270 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
23280 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
23290 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
232a0 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
232b0 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
232c0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
232d0 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
232e0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
232f0 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
23300 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
23310 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
23320 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
23330 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
23340 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
23350 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
23360 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
23370 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
23380 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
23390 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
233a0 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
233b0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
233c0 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
233d0 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
233e0 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
233f0 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
23400 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
23410 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
23420 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
23430 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
23440 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
23450 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
23460 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
23470 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
23480 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
23490 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
234a0 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
234b0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
234c0 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
234d0 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
234e0 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
234f0 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
23500 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
23510 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
23520 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
23530 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
23540 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
23550 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
23560 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
23570 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
23580 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
23590 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
235a0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
235b0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
235c0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
235d0 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
235e0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
235f0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
23600 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
23610 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
23620 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
23630 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
23640 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
23650 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
23660 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
23670 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
23680 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
23690 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
236a0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
236b0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
236c0 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
236d0 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
236e0 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
236f0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
23700 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
23710 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
23720 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23730 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
23740 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
23750 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
23760 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
23770 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
23780 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
23790 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
237a0 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
237b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
237c0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
237d0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
237e0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
237f0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
23800 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
23810 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
23820 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
23830 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
23840 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
23850 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
23860 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
23870 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
23880 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
23890 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
238a0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
238b0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
238c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
238d0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
238e0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
238f0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
23900 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
23910 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
23920 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
23930 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
23940 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
23950 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
23960 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
23970 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
23980 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
23990 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
239a0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
239b0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
239c0 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
239d0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
239e0 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
239f0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
23a00 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
23a10 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
23a20 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
23a30 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
23a40 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
23a50 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
23a60 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
23a70 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
23a80 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
23a90 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
23aa0 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
23ab0 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
23ac0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
23ad0 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
23ae0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
23af0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
23b00 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
23b10 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
23b20 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
23b30 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
23b40 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
23b50 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
23b60 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
23b70 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
23b80 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
23b90 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
23ba0 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
23bb0 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
23bc0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
23bd0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
23be0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
23bf0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
23c00 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
23c10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
23c20 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
23c30 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
23c40 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
23c50 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
23c60 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
23c70 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
23c80 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
23c90 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
23ca0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
23cb0 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
23cc0 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
23cd0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
23ce0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23cf0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
23d00 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
23d10 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
23d20 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
23d30 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
23d40 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
23d50 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
23d60 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
23d70 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
23d80 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
23d90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
23da0 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
23db0 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
23dc0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
23dd0 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
23de0 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
23df0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
23e00 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
23e10 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
23e20 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
23e30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
23e40 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23e50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
23e60 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
23e70 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
23e80 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
23e90 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
23ea0 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
23eb0 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
23ec0 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
23ed0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
23ee0 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
23ef0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
23f00 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
23f10 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
23f20 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
23f30 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
23f40 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
23f50 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
23f60 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23f70 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
23f80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23f90 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
23fa0 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
23fb0 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
23fc0 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
23fd0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
23fe0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
23ff0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
24000 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
24010 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
24020 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
24030 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
24040 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
24050 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
24060 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
24070 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
24080 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
24090 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
240a0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
240b0 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
240c0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
240d0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
240e0 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
240f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
24100 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
24110 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
24120 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
24130 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
24140 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
24150 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
24160 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
24170 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
24180 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
24190 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
241a0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
241b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
241c0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
241d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
241e0 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
241f0 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
24200 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24210 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
24220 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
24230 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
24240 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
24250 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
24260 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
24270 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
24280 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
24290 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
242a0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
242b0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
242c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
242d0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
242e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
242f0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
24300 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
24310 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24320 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
24330 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
24340 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
24350 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
24360 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
24370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
24380 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
24390 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
243a0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
243b0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
243c0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
243d0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
243e0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
243f0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
24400 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
24410 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
24420 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
24430 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
24440 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
24450 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
24460 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24470 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
24480 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24490 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
244a0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
244b0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
244c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
244d0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
244e0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
244f0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
24500 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
24510 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
24520 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
24530 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
24540 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
24550 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
24560 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
24570 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
24580 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
24590 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
245a0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
245b0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
245c0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
245d0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
245e0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
245f0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
24600 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
24610 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
24620 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
24630 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
24640 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
24650 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
24660 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24670 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
24680 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
24690 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
246a0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
246b0 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
246c0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
246d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
246e0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
246f0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
24700 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
24710 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
24720 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
24730 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
24740 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
24750 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
24760 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
24770 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
24780 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
24790 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
247a0 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
247b0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
247c0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
247d0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
247e0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
247f0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
24800 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
24810 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
24820 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
24830 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
24840 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
24850 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
24860 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
24870 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
24880 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
24890 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
248a0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
248b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
248c0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
248d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
248e0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
248f0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
24900 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
24910 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
24920 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
24930 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
24940 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
24950 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
24960 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
24970 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
24980 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
24990 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
249a0 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
249b0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
249c0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
249d0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
249e0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
249f0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
24a00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
24a10 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
24a20 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
24a30 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
24a40 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
24a50 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
24a60 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
24a70 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
24a80 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
24a90 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
24aa0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
24ab0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
24ac0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
24ad0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
24ae0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
24af0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24b00 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
24b10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24b20 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
24b30 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
24b40 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
24b50 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
24b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
24b70 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
24b80 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
24b90 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
24ba0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
24bb0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
24bc0 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
24bd0 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
24be0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
24bf0 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
24c00 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
24c10 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
24c20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
24c30 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
24c40 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
24c50 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
24c60 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
24c70 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
24c80 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
24c90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24ca0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
24cb0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
24cc0 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
24cd0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
24ce0 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
24cf0 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
24d00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
24d10 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
24d20 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
24d30 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
24d40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
24d50 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
24d60 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
24d70 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
24d80 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
24d90 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
24da0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
24db0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
24dc0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
24dd0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
24de0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
24df0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
24e00 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
24e10 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
24e20 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
24e30 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
24e40 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
24e50 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
24e60 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
24e70 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
24e80 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
24e90 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
24ea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
24eb0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
24ec0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
24ed0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
24ee0 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
24ef0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
24f00 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
24f10 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
24f20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
24f30 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
24f40 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
24f50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24f60 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
24f70 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
24f80 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
24f90 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
24fa0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
24fb0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
24fc0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
24fd0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
24fe0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
24ff0 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
25000 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
25010 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
25020 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
25030 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
25040 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
25050 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
25060 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
25070 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
25080 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
25090 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
250a0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
250b0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
250c0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
250d0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
250e0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
250f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
25100 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
25110 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
25120 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
25130 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
25140 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
25150 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
25160 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
25170 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
25180 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
25190 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
251a0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
251b0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
251c0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
251d0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
251e0 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
251f0 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
25200 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
25210 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
25220 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
25230 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
25240 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25250 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
25260 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
25270 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
25280 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
25290 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
252a0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
252b0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
252c0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
252d0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
252e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
252f0 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
25300 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
25310 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
25320 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
25330 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
25340 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
25350 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
25360 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
25370 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
25380 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
25390 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
253a0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
253b0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
253c0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
253d0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
253e0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
253f0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
25400 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
25410 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
25420 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
25430 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
25440 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
25450 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
25460 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
25470 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
25480 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
25490 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
254a0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
254b0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
254c0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
254d0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
254e0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
254f0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
25500 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
25510 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
25520 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
25530 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
25540 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
25550 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
25560 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
25570 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
25580 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
25590 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
255a0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
255b0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
255c0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
255d0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
255e0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
255f0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
25600 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
25610 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
25620 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
25630 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
25640 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
25650 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
25660 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
25670 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
25680 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
25690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
256a0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
256b0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
256c0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
256d0 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
256e0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
256f0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
25700 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
25710 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
25720 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
25730 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
25740 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
25750 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
25760 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
25770 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
25780 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
25790 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
257a0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
257b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
257c0 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
257d0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
257e0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
257f0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
25800 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
25810 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25820 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
25830 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25840 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
25850 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
25860 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
25870 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
25880 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25890 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
258a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
258b0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
258c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
258d0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
258e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
258f0 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
25900 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25910 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
25920 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25930 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
25940 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25950 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
25960 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
25970 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
25980 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
25990 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
259a0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
259b0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
259c0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
259d0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
259e0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
259f0 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
25a00 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25a10 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
25a20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25a30 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
25a40 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25a50 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
25a60 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
25a70 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
25a80 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25a90 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
25aa0 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
25ab0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25ac0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
25ad0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25ae0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
25af0 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
25b00 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
25b10 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
25b20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25b30 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
25b40 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25b50 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
25b60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25b70 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
25b80 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
25b90 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
25ba0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
25bb0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
25bc0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
25bd0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
25be0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
25bf0 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
25c00 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
25c10 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
25c20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
25c30 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
25c40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25c50 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
25c60 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25c70 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
25c80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25c90 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25ca0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
25cb0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
25cc0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25cd0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
25ce0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25cf0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
25d00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25d10 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25d20 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
25d30 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
25d40 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
25d50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
25d60 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
25d70 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
25d80 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
25d90 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
25da0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25db0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
25dc0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
25dd0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
25de0 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
25df0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
25e00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25e10 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
25e20 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
25e30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
25e40 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
25e50 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25e60 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
25e70 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
25e80 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
25e90 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
25ea0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25eb0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
25ec0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25ed0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
25ee0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
25ef0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
25f00 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
25f10 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
25f20 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
25f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25f40 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
25f50 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
25f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25f70 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
25f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
25f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25fa0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
25fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
25fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25fd0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
25fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25ff0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
26000 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
26010 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
26020 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
26030 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
26040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26050 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
26060 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
26070 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
26080 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
26090 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
260a0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
260b0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
260c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
260d0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
260e0 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
260f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
26100 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
26110 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
26120 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
26130 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
26140 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20        10../*.** 
26150 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
26160 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
26170 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
26180 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
26190 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
261a0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
261b0 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
261c0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
261d0 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
261e0 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
261f0 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
26200 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
26210 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
26220 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
26230 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
26240 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
26250 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
26260 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
26270 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
26280 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
26290 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
262a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
262b0 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
262c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
262d0 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
262e0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
262f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
26300 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
26310 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
26320 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
26330 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
26340 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
26350 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
26360 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
26370 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26380 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
26390 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
263a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
263b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
263c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
263d0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
263e0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
263f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
26400 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
26410 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
26420 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
26430 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
26440 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
26450 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
26460 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
26470 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
26480 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
26490 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20  om zSql.  ^When 
264a0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
264b0 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
264c0 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
264d0 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
264e0 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
264f0 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
26500 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
26510 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
26520 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
26530 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
26540 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
26550 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
26560 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
26570 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
26580 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
26590 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
265a0 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
265b0 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
265c0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
265d0 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
265e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
265f0 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
26600 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
26610 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
26620 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
26630 62 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61  bytes as this sa
26640 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20  ves SQLite from 
26650 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b  having to.** mak
26660 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
26670 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a  input string..**
26680 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
26690 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
266a0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
266b0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
266c0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
266d0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
266e0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
266f0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
26700 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
26710 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
26720 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
26730 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
26740 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
26750 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
26760 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
26770 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
26780 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
26790 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
267a0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
267b0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
267c0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
267d0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
267e0 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
267f0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
26800 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
26810 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
26820 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
26830 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
26840 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
26850 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
26860 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
26870 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
26880 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
26890 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
268a0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
268b0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
268c0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
268d0 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
268e0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
268f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
26900 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
26910 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
26920 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
26930 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
26940 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
26950 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
26960 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
26970 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
26980 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
26990 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
269a0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
269b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
269c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
269d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
269e0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
269f0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
26a00 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
26a10 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
26a20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
26a30 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
26a40 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
26a50 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
26a60 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
26a70 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
26a80 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
26a90 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
26aa0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
26ab0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
26ac0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
26ad0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
26ae0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
26af0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
26b00 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
26b10 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
26b20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
26b30 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
26b40 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
26b50 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
26b60 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
26b70 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
26b80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
26b90 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
26ba0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
26bb0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
26bc0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
26bd0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
26be0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
26bf0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
26c00 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
26c10 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
26c20 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
26c30 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
26c40 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
26c50 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
26c60 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
26c70 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
26c80 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
26c90 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
26ca0 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
26cb0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
26cc0 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
26cd0 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
26ce0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
26cf0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
26d00 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
26d10 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
26d20 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
26d30 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
26d40 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
26d50 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
26d60 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
26d70 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
26d80 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
26d90 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
26da0 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
26db0 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
26dc0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
26dd0 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
26de0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
26df0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
26e00 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
26e10 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
26e20 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
26e30 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
26e40 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
26e50 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
26e60 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
26e70 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
26e80 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
26e90 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
26ea0 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
26eb0 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
26ec0 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
26ed0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
26ee0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
26ef0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
26f00 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
26f10 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
26f20 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
26f30 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
26f40 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
26f50 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
26f60 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
26f70 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
26f80 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
26f90 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
26fa0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
26fb0 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
26fc0 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
26fd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
26fe0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
26ff0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
27000 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
27010 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
27020 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
27030 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
27040 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
27050 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
27060 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
27070 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
27080 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
27090 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
270a0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
270b0 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
270c0 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
270d0 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
270e0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
270f0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
27100 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
27110 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
27120 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
27130 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
27140 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
27150 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
27160 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
27170 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
27180 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
27190 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
271a0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
271b0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
271c0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
271d0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
271e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
271f0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
27200 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
27210 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
27220 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
27230 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
27240 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
27250 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
27260 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
27270 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
27280 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
27290 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
272a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
272b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
272c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
272d0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
272e0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
272f0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
27300 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
27310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
27320 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
27330 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
27340 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
27350 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
27360 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
27370 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27380 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
27390 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
273a0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
273b0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
273c0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
273d0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
273e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
273f0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
27400 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
27410 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
27420 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
27430 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
27440 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
27450 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
27460 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
27470 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
27480 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
27490 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
274a0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
274b0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
274c0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
274d0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
274e0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
274f0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
27500 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
27510 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27520 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
27530 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
27540 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
27550 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
27560 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
27570 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
27580 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
27590 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
275a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
275b0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
275c0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
275d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
275e0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
275f0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
27600 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27610 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
27620 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
27630 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
27640 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
27650 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
27660 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
27670 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
27680 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
27690 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
276a0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
276b0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
276c0 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
276d0 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
276e0 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
276f0 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
27700 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
27710 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
27720 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
27730 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27740 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
27750 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
27760 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
27770 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
27780 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
27790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
277a0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
277b0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
277c0 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
277d0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
277e0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
277f0 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
27800 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
27810 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
27820 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
27830 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27840 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
27850 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
27860 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
27870 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
27880 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
27890 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
278a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
278b0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
278c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
278d0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
278e0 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
278f0 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
27900 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
27910 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
27920 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
27930 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
27940 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
27950 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
27960 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
27970 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
27980 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
27990 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
279a0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
279b0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
279c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
279d0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
279e0 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
279f0 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
27a00 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
27a10 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
27a20 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
27a30 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
27a40 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
27a50 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
27a60 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
27a70 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
27a80 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
27a90 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
27aa0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
27ab0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
27ac0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
27ad0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
27ae0 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
27af0 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
27b00 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
27b10 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
27b20 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27b30 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
27b40 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
27b50 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
27b60 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
27b70 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
27b80 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
27b90 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
27ba0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
27bb0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
27bc0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
27bd0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
27be0 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
27bf0 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
27c00 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
27c10 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
27c20 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
27c30 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
27c40 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
27c50 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
27c60 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
27c70 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
27c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27c90 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
27ca0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
27cb0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
27cc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27cd0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
27ce0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
27cf0 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
27d00 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
27d10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27d20 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
27d30 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
27d40 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
27d50 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
27d60 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
27d70 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27d80 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
27d90 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
27da0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27db0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
27dc0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
27dd0 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
27de0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
27df0 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
27e00 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
27e10 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
27e20 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
27e30 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
27e40 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
27e50 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
27e60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
27e70 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
27e80 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
27e90 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
27ea0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
27eb0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
27ec0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
27ed0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
27ee0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
27ef0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
27f00 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
27f10 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
27f20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
27f30 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
27f40 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
27f50 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
27f60 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
27f70 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
27f80 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
27f90 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
27fa0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
27fb0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
27fc0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
27fd0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
27fe0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
27ff0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
28000 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
28010 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
28020 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
28030 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
28040 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
28050 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
28060 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
28070 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
28080 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
28090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
280a0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
280b0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
280c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
280d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
280e0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
280f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28100 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
28110 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
28120 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
28130 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
28140 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
28150 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
28160 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
28170 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
28180 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
28190 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
281a0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
281b0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
281c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
281d0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
281e0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
281f0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
28200 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
28210 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
28220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28230 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
28240 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
28250 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
28260 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
28270 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
28280 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28290 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
282a0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
282b0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
282c0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
282d0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
282e0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
282f0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
28300 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
28310 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
28320 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
28330 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
28340 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
28350 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28360 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
28370 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
28380 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
28390 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
283a0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
283b0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
283c0 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
283d0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
283e0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
283f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28400 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
28410 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
28420 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
28430 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28440 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
28450 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
28460 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
28470 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
28480 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
28490 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
284a0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
284b0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
284c0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
284d0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
284e0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
284f0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
28500 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
28510 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
28520 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
28530 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
28540 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
28550 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
28560 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
28570 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
28580 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
28590 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
285a0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
285b0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
285c0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
285d0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
285e0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
285f0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
28600 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
28610 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
28620 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
28630 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
28640 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
28650 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
28660 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
28670 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
28680 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
28690 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
286a0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
286b0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
286c0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
286d0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
286e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
286f0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
28700 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
28710 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
28720 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
28730 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
28740 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
28750 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
28760 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
28770 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28780 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
28790 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
287a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
287b0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
287c0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
287d0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
287e0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
287f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
28800 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
28810 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
28820 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
28830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28840 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
28850 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
28860 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
28870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
28880 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
28890 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
288a0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
288b0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
288c0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
288d0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
288e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
288f0 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
28900 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
28910 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
28920 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
28930 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
28940 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
28950 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
28960 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
28970 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28980 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
28990 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
289a0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
289b0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
289c0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
289d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
289e0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
289f0 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
28a00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28a10 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
28a20 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
28a30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
28a40 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
28a50 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
28a60 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
28a70 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
28a80 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
28a90 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
28aa0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
28ab0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
28ac0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28ad0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
28ae0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
28af0 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
28b00 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
28b10 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
28b20 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
28b30 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
28b40 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
28b50 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
28b60 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
28b70 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
28b80 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
28b90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
28ba0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
28bb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28bc0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
28bd0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
28be0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
28bf0 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
28c00 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
28c10 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
28c20 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
28c30 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
28c40 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
28c50 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
28c60 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
28c70 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
28c80 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
28c90 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
28ca0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
28cb0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
28cc0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
28cd0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
28ce0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
28cf0 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
28d00 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
28d10 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
28d20 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
28d30 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
28d40 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
28d50 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
28d60 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
28d70 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
28d80 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
28d90 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
28da0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
28db0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
28dc0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
28dd0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
28de0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
28df0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
28e00 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
28e10 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
28e20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
28e30 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
28e40 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
28e50 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
28e60 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
28e70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
28e80 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
28e90 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
28ea0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
28eb0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
28ec0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
28ed0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
28ee0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
28ef0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
28f00 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
28f10 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
28f20 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
28f30 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
28f40 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
28f50 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
28f60 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
28f70 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
28f80 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
28f90 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28fa0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
28fb0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
28fc0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
28fd0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
28fe0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
28ff0 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
29000 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
29010 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
29020 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
29030 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
29040 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
29050 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
29060 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
29070 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
29080 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
29090 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
290a0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
290b0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
290c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
290d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
290e0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
290f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
29100 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
29110 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
29120 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
29130 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
29140 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
29150 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
29160 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
29170 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
29180 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
29190 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
291a0 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
291b0 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
291c0 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
291d0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
291e0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
291f0 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
29200 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
29210 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
29220 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
29230 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
29240 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
29250 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
29260 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
29270 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
29280 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29290 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
292a0 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
292b0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
292c0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
292d0 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
292e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
292f0 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
29300 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
29310 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
29320 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
29330 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
29340 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
29350 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
29360 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
29370 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
29380 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
29390 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
293a0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
293b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
293c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
293d0 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e  nd_text16() then
293e0 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
293f0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
29400 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
29410 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
29420 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
29430 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
29440 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
29450 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
29460 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
29470 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
29480 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
29490 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
294a0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
294b0 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
294c0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
294d0 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
294e0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
294f0 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
29500 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
29510 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
29520 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
29530 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
29540 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
29550 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
29560 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
29570 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
29580 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
29590 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
295a0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
295b0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
295c0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
295d0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
295e0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
295f0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
29600 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
29610 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
29620 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
29630 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
29640 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
29650 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
29660 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
29670 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
29680 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
29690 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
296a0 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
296b0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
296c0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
296d0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
296e0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
296f0 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
29700 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
29710 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
29720 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
29730 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
29740 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
29750 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
29760 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
29770 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
29780 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
29790 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
297a0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
297b0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
297c0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
297d0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
297e0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
297f0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
29800 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
29810 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
29820 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
29830 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
29840 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
29850 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
29860 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
29870 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
29880 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
29890 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
298a0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
298b0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
298c0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
298d0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
298e0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
298f0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
29900 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
29910 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
29920 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
29930 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
29940 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
29950 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
29960 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
29970 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
29980 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
29990 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
299a0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
299b0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
299c0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
299d0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
299e0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
299f0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
29a00 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
29a10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29a20 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
29a30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29a40 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
29a50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29a60 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
29a70 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
29a80 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
29a90 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
29aa0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
29ab0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
29ac0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
29ad0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
29ae0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
29af0 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
29b00 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
29b10 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
29b20 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
29b30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
29b40 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
29b50 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
29b60 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
29b70 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
29b80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
29b90 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
29ba0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
29bb0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
29bc0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
29bd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
29be0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
29bf0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
29c00 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
29c10 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
29c20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
29c30 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
29c40 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
29c50 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
29c60 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
29c70 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
29c80 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
29c90 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
29ca0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
29cb0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29cc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29cd0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
29ce0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29cf0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
29d00 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
29d10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29d20 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
29d30 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
29d40 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
29d50 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
29d60 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
29d70 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
29d80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
29d90 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
29da0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
29db0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
29dc0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
29dd0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
29de0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29df0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
29e00 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
29e10 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
29e20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
29e30 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
29e40 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
29e50 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
29e60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29e70 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
29e80 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
29e90 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
29ea0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
29eb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29ec0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
29ed0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
29ee0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
29ef0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
29f00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29f10 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
29f20 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
29f30 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
29f40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29f50 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
29f60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
29f70 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
29f80 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
29f90 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
29fa0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
29fb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
29fc0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
29fd0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
29fe0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
29ff0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2a000 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2a010 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2a020 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2a030 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2a040 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2a050 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2a060 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2a070 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a080 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2a090 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2a0a0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2a0b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2a0c0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2a0d0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2a0e0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2a0f0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2a100 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2a110 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2a120 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2a130 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2a140 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2a150 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2a160 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2a170 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2a180 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2a190 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2a1a0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2a1b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a1c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a1d0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2a1e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2a1f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2a200 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2a210 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a220 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2a230 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2a240 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2a250 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2a260 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a270 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2a280 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2a290 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a2a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a2b0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2a2c0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2a2d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2a2e0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2a2f0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2a300 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a310 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2a320 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2a330 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2a340 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2a350 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2a360 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2a370 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2a380 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2a390 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2a3a0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2a3b0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2a3c0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2a3d0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2a3e0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2a3f0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2a400 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2a410 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2a420 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2a430 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2a440 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2a450 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2a460 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2a470 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2a480 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2a490 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2a4a0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2a4b0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2a4c0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2a4d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2a4e0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2a4f0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2a500 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2a510 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2a520 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2a530 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2a540 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2a550 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2a560 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2a570 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2a580 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2a590 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2a5a0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2a5b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a5c0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2a5d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2a5e0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2a5f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2a600 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2a610 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2a620 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a630 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2a640 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2a650 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2a660 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
2a670 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a680 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2a690 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2a6a0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2a6b0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2a6c0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2a6d0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2a6e0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2a6f0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2a700 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2a710 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2a720 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2a730 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2a740 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2a750 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2a760 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2a770 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2a780 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2a790 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2a7a0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2a7b0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2a7c0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2a7d0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2a7e0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2a7f0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2a800 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2a810 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2a820 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2a830 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2a840 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a850 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2a860 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2a870 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2a880 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2a890 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2a8a0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2a8b0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2a8c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a8d0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2a8e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a8f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2a900 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a910 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2a920 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2a930 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2a940 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2a950 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2a960 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
2a970 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
2a980 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
2a990 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
2a9a0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
2a9b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2a9c0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
2a9d0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2a9e0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2a9f0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
2aa00 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
2aa10 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
2aa20 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
2aa30 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2aa40 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2aa50 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2aa60 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2aa70 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
2aa80 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
2aa90 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2aaa0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2aab0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2aac0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2aad0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2aae0 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2aaf0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2ab00 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2ab10 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2ab20 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2ab30 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2ab40 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2ab50 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2ab60 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2ab70 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
2ab80 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2ab90 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2aba0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2abb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2abc0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2abd0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2abe0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2abf0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2ac00 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
2ac10 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
2ac20 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
2ac30 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2ac40 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
2ac50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2ac60 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
2ac70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2ac80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2ac90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2aca0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
2acb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2acc0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
2acd0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2ace0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2acf0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
2ad00 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
2ad10 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2ad20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ad30 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
2ad40 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
2ad50 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2ad60 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2ad70 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2ad80 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
2ad90 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2ada0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
2adb0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
2adc0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
2add0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
2ade0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
2adf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ae00 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
2ae10 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2ae20 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2ae30 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2ae40 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2ae50 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2ae60 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2ae70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2ae80 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2ae90 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2aea0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
2aeb0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
2aec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2aed0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
2aee0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
2aef0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
2af00 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
2af10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
2af20 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
2af30 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2af40 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2af50 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2af60 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2af70 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2af80 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2af90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2afa0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2afb0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2afc0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2afd0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2afe0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2aff0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2b000 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2b010 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2b020 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2b030 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2b040 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2b050 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2b060 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2b070 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2b080 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2b090 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2b0a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b0b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b0c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b0d0 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
2b0e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b0f0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2b100 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2b110 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b120 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
2b130 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
2b140 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2b150 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2b160 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2b170 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2b180 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2b190 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2b1a0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2b1b0 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2b1c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2b1d0 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2b1e0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2b1f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2b200 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2b210 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2b220 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2b230 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2b240 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2b250 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2b260 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2b270 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2b280 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2b290 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2b2a0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2b2b0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2b2c0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2b2d0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2b2e0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2b2f0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2b300 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2b310 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b320 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2b330 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2b340 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2b350 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2b360 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2b370 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2b380 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2b390 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2b3a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2b3b0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2b3c0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2b3d0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2b3e0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2b3f0 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2b400 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2b410 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2b420 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2b430 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2b440 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2b450 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2b460 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2b470 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2b480 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2b490 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2b4a0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2b4b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2b4c0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2b4d0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2b4e0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2b4f0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2b500 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2b510 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2b520 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2b530 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2b540 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2b550 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2b560 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2b570 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2b580 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2b590 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2b5a0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2b5b0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2b5c0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2b5d0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2b5e0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2b5f0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2b600 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2b610 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2b620 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2b630 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2b640 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2b650 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2b660 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2b670 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2b680 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2b690 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2b6a0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2b6b0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2b6c0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2b6d0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2b6e0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2b6f0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2b700 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2b710 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2b720 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2b730 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2b740 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2b750 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2b760 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2b770 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2b780 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2b790 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2b7a0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2b7b0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2b7c0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2b7d0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2b7e0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2b7f0 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2b800 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2b810 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2b820 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2b830 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2b840 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2b850 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b860 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2b870 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2b880 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2b890 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2b8a0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2b8b0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2b8c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2b8d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b8e0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2b8f0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2b900 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2b910 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2b920 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b930 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2b940 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2b950 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2b960 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2b970 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2b980 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2b990 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2b9a0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2b9b0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2b9c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b9d0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2b9e0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2b9f0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2ba00 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2ba10 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2ba20 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2ba30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2ba40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2ba50 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2ba60 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2ba70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ba80 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2ba90 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2baa0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2bab0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2bac0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2bad0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2bae0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2baf0 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2bb00 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2bb10 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2bb20 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
2bb30 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
2bb40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2bb50 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
2bb60 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
2bb70 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
2bb80 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2bb90 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
2bba0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
2bbb0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
2bbc0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
2bbd0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
2bbe0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2bbf0 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
2bc00 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
2bc10 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
2bc20 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2bc30 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
2bc40 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2bc50 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
2bc60 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2bc70 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
2bc80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2bc90 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
2bca0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2bcb0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
2bcc0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
2bcd0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
2bce0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
2bcf0 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
2bd00 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
2bd10 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
2bd20 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
2bd30 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
2bd40 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
2bd50 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
2bd60 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
2bd70 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
2bd80 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
2bd90 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
2bda0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
2bdb0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
2bdc0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
2bdd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2bde0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
2bdf0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
2be00 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
2be10 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2be20 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
2be30 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
2be40 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
2be50 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
2be60 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
2be70 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
2be80 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
2be90 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
2bea0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
2beb0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
2bec0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
2bed0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
2bee0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
2bef0 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
2bf00 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
2bf10 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
2bf20 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
2bf30 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
2bf40 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
2bf50 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
2bf60 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
2bf70 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2bf80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2bf90 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2bfa0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2bfb0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2bfc0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2bfd0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2bfe0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2bff0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2c000 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2c010 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2c020 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c030 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2c040 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2c050 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2c060 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2c070 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c080 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2c090 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2c0a0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2c0b0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2c0c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2c0d0 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2c0e0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2c0f0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2c100 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2c110 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2c120 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2c130 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2c140 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2c150 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2c160 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2c170 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2c180 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2c190 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2c1a0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2c1b0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2c1c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c1d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2c1e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2c1f0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2c200 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2c210 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c220 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c230 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2c240 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2c250 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2c260 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2c270 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2c280 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2c290 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2c2a0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2c2b0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2c2c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2c2d0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2c2e0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2c2f0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2c300 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2c310 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2c320 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2c330 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2c340 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2c350 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2c360 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2c370 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2c380 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2c390 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2c3a0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2c3b0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2c3c0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2c3d0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2c3e0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2c3f0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2c400 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2c410 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2c420 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2c430 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2c440 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2c450 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2c460 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2c470 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2c480 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2c490 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2c4a0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2c4b0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2c4c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2c4d0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2c4e0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2c4f0 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2c500 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2c510 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2c520 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2c530 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2c540 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2c550 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2c560 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2c570 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2c580 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2c590 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2c5a0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2c5b0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2c5c0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2c5d0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2c5e0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2c5f0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2c600 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2c610 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2c620 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2c630 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2c640 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2c650 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2c660 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2c670 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2c680 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2c690 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2c6a0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2c6b0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2c6c0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2c6d0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2c6e0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2c6f0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2c700 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2c710 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2c720 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2c730 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2c740 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2c750 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2c760 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2c770 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2c780 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2c790 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2c7a0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2c7b0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2c7c0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2c7d0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2c7e0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2c7f0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2c800 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2c810 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2c820 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2c830 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2c840 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2c850 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2c860 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2c870 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2c880 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2c890 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2c8a0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2c8b0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2c8c0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2c8d0 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2c8e0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2c8f0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2c900 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2c910 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2c920 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2c930 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2c940 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2c950 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2c960 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2c970 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2c980 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2c990 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2c9a0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2c9b0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2c9c0 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2c9d0 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2c9e0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2c9f0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2ca00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2ca10 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2ca20 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2ca30 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2ca40 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2ca50 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2ca60 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2ca70 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2ca80 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2ca90 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2caa0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2cab0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2cac0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2cad0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2cae0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2caf0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2cb00 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2cb10 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2cb20 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2cb30 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2cb40 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2cb50 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2cb60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2cb70 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2cb80 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2cb90 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2cba0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2cbb0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2cbc0 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2cbd0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2cbe0 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2cbf0 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2cc00 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2cc10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cc20 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2cc30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2cc40 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2cc50 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2cc60 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2cc70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2cc80 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2cc90 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2cca0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2ccb0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2ccc0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2ccd0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2cce0 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2ccf0 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2cd00 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2cd10 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2cd20 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2cd30 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2cd40 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2cd50 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2cd60 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2cd70 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2cd80 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2cd90 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2cda0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2cdb0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2cdc0 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2cdd0 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2cde0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2cdf0 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2ce00 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2ce10 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2ce20 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2ce30 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2ce40 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2ce50 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2ce60 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2ce70 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2ce80 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2ce90 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2cea0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2ceb0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2cec0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2ced0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2cee0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2cef0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2cf00 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2cf10 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2cf20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2cf30 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2cf40 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2cf50 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2cf60 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2cf70 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2cf80 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2cf90 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2cfa0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2cfb0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2cfc0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2cfd0 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2cfe0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2cff0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2d000 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2d010 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d020 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2d030 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2d040 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2d050 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2d060 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2d070 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d080 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2d090 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2d0a0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2d0b0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2d0c0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2d0d0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2d0e0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2d0f0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2d100 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2d110 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2d120 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2d130 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2d140 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2d150 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2d160 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2d170 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2d180 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2d190 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2d1a0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2d1b0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2d1c0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2d1d0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2d1e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d1f0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2d200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2d210 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2d220 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2d230 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2d240 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2d250 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2d260 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2d270 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2d280 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2d290 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2d2a0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2d2b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2d2c0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2d2d0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2d2e0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2d2f0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2d300 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2d310 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2d320 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2d330 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2d340 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d350 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2d360 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2d370 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2d380 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2d390 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2d3a0 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2d3b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d3c0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2d3d0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2d3e0 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2d3f0 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2d400 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2d410 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2d420 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2d430 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2d440 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2d450 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2d460 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2d470 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2d480 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2d490 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2d4a0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
2d4b0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2d4c0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2d4d0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2d4e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2d4f0 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2d500 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2d510 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2d520 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2d530 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2d540 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2d550 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2d560 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2d570 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2d580 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2d590 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2d5a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2d5b0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2d5c0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2d5d0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2d5e0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2d5f0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2d600 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2d610 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2d620 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2d630 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2d640 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2d650 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2d660 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2d670 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2d680 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2d690 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2d6a0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2d6b0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2d6c0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2d6d0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2d6e0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2d6f0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2d700 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2d710 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2d720 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2d730 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2d740 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2d750 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2d760 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2d770 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2d780 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2d790 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2d7a0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2d7b0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2d7c0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2d7d0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2d7e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d7f0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2d800 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2d810 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2d820 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2d830 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2d840 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2d850 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2d860 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2d870 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2d880 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2d890 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2d8a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2d8b0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2d8c0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2d8d0 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2d8e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2d8f0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2d900 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2d910 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d920 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2d930 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2d940 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2d950 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2d960 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2d970 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2d980 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2d990 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2d9a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2d9b0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2d9c0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2d9d0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2d9e0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2d9f0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2da00 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2da10 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2da20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2da30 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2da40 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2da50 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2da60 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2da70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2da80 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2da90 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2daa0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2dab0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2dac0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2dad0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2dae0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2daf0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2db00 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2db10 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2db20 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2db30 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2db40 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2db50 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2db60 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2db70 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2db80 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2db90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2dba0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2dbb0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2dbc0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2dbd0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2dbe0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2dbf0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2dc00 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2dc10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2dc20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2dc30 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2dc40 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2dc50 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2dc60 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2dc70 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2dc80 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2dc90 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2dca0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2dcb0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2dcc0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2dcd0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2dce0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2dcf0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2dd00 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2dd10 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2dd20 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2dd30 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2dd40 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2dd50 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2dd60 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2dd70 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2dd80 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2dd90 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2dda0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2ddb0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2ddc0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2ddd0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2dde0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2ddf0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2de00 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2de10 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2de20 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2de30 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2de40 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2de50 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2de60 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2de70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2de80 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2de90 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2dea0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2deb0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2dec0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2ded0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2dee0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2def0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2df00 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2df10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2df20 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2df30 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2df40 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2df50 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2df60 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2df70 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2df80 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2df90 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2dfa0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2dfb0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2dfc0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2dfd0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2dfe0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2dff0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2e000 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2e010 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2e020 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2e030 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2e040 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2e050 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2e060 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2e070 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2e080 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2e090 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2e0a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2e0b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2e0c0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2e0d0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2e0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e0f0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2e100 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2e110 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2e120 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2e130 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2e140 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2e150 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2e160 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2e170 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e180 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2e190 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e1a0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2e1b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2e1c0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2e1d0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2e1e0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2e1f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e200 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2e210 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2e220 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2e230 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2e240 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e250 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2e260 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2e270 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e280 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2e290 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2e2a0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2e2b0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2e2c0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2e2d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e2e0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2e2f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2e300 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2e310 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2e320 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2e330 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2e340 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2e350 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2e360 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2e370 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2e380 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2e390 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2e3a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2e3b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2e3c0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2e3d0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2e3e0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2e3f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e400 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2e410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e420 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2e430 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2e440 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2e450 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2e460 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2e470 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2e480 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2e490 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e4a0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2e4b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e4c0 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2e4d0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2e4e0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2e4f0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2e500 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2e510 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2e520 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2e530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e540 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2e550 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2e560 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2e570 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2e580 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2e590 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2e5a0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2e5b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e5c0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2e5d0 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2e5e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2e5f0 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2e600 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2e610 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2e620 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2e630 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2e640 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2e650 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2e660 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2e670 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2e680 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2e690 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2e6a0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2e6b0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2e6c0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2e6d0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e6e0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e6f0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2e700 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2e710 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2e720 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2e730 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2e740 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2e750 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2e760 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2e770 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e780 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2e790 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2e7a0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2e7b0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2e7c0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2e7d0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2e7e0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2e7f0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2e800 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2e810 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2e820 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2e830 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2e840 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2e850 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2e860 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2e870 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2e880 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2e890 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2e8a0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2e8b0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2e8c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2e8d0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2e8e0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2e8f0 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2e900 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2e910 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2e920 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2e930 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2e940 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2e950 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2e960 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2e970 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2e980 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2e990 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2e9a0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2e9b0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2e9c0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2e9d0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2e9e0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2e9f0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2ea00 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2ea10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2ea20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2ea30 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2ea40 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2ea50 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2ea60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2ea70 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2ea80 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2ea90 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2eaa0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2eab0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2eac0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2ead0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2eae0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2eaf0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2eb00 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2eb10 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2eb20 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2eb30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2eb40 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2eb50 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2eb60 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2eb70 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2eb80 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2eb90 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2eba0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2ebb0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2ebc0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2ebd0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2ebe0 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
2ebf0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2ec00 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2ec10 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2ec20 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2ec30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2ec40 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2ec50 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2ec60 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2ec70 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2ec80 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2ec90 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2eca0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2ecb0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2ecc0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2ecd0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2ece0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2ecf0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2ed00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2ed10 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2ed20 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2ed30 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2ed40 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2ed50 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2ed60 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2ed70 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2ed80 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2ed90 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2eda0 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2edb0 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2edc0 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2edd0 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2ede0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2edf0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2ee00 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2ee10 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2ee20 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2ee30 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2ee40 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2ee50 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2ee60 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2ee70 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2ee80 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2ee90 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2eea0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2eeb0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2eec0 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2eed0 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2eee0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2eef0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ef00 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2ef10 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2ef20 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2ef30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2ef40 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2ef50 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2ef60 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2ef70 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2ef80 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2ef90 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2efa0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2efb0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2efc0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2efd0 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2efe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2eff0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2f000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f010 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2f020 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2f030 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2f040 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2f050 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2f060 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2f070 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2f080 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2f090 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2f0a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2f0b0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2f0c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f0d0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2f0e0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2f0f0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2f100 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2f110 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2f120 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2f130 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2f140 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2f150 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2f160 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2f170 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2f180 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2f190 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2f1a0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2f1b0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2f1c0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2f1d0 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2f1e0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2f1f0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2f200 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2f210 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2f220 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2f230 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2f240 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2f250 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2f260 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2f270 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2f280 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2f290 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2f2a0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2f2b0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2f2c0 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2f2d0 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2f2e0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2f2f0 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2f300 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2f310 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2f320 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2f330 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2f340 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2f350 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2f360 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2f370 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2f380 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2f390 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2f3a0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2f3b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2f3c0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2f3d0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2f3e0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2f3f0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2f400 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2f410 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2f420 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2f430 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f440 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2f450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f460 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2f470 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2f480 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2f490 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2f4a0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2f4b0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2f4c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f4d0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2f4e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2f4f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2f500 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2f510 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2f520 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2f530 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2f540 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2f550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f560 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2f570 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f580 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2f590 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2f5a0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2f5b0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2f5c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2f5d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2f5e0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2f5f0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2f600 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f610 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2f620 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2f630 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f640 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2f650 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2f660 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2f670 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2f680 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2f690 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2f6a0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2f6b0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2f6c0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2f6d0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2f6e0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2f6f0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2f700 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2f710 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2f720 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2f730 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2f740 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2f750 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2f760 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2f770 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2f780 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2f790 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
2f7a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f7b0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2f7c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2f7d0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2f7e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2f7f0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2f800 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2f810 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2f820 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2f830 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2f840 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2f850 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2f860 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2f870 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2f880 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2f890 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2f8a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2f8b0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2f8c0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2f8d0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2f8e0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2f8f0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2f900 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2f910 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
2f920 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f930 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2f940 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f950 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2f960 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f970 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f980 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2f990 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f9a0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
2f9b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
2f9c0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2f9d0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2f9e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f9f0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2fa00 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
2fa10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2fa20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
2fa30 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
2fa40 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
2fa50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2fa60 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
2fa70 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2fa80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
2fa90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2faa0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
2fab0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2fac0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
2fad0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2fae0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2faf0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
2fb00 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2fb10 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
2fb20 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2fb30 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2fb40 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2fb50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fb60 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2fb70 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2fb80 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
2fb90 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2fba0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2fbb0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2fbc0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2fbd0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
2fbe0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2fbf0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2fc00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
2fc10 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
2fc20 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
2fc30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
2fc40 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
2fc50 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
2fc60 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
2fc70 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
2fc80 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
2fc90 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2fca0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
2fcb0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
2fcc0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2fcd0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
2fce0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2fcf0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
2fd00 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2fd10 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2fd20 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2fd30 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
2fd40 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2fd50 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
2fd60 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
2fd70 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
2fd80 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
2fd90 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
2fda0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
2fdb0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
2fdc0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
2fdd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2fde0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
2fdf0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
2fe00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2fe10 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
2fe20 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2fe30 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
2fe40 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2fe50 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
2fe60 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
2fe70 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
2fe80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
2fe90 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2fea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
2feb0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
2fec0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
2fed0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fee0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
2fef0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
2ff00 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
2ff10 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
2ff20 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2ff30 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
2ff40 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
2ff50 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2ff60 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2ff70 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
2ff80 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
2ff90 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2ffa0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2ffb0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
2ffc0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
2ffd0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
2ffe0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
2fff0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
30000 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
30010 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
30020 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
30030 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
30040 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
30050 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
30060 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
30070 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30080 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
30090 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
300a0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
300b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
300c0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
300d0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
300e0 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
300f0 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
30100 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
30110 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
30120 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
30130 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
30140 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
30150 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
30160 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
30170 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
30180 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
30190 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
301a0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
301b0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
301c0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
301d0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
301e0 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
301f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30200 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
30210 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
30220 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
30230 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
30240 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
30250 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
30260 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
30270 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30280 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
30290 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
302a0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
302b0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
302c0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
302d0 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
302e0 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
302f0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
30300 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
30310 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
30320 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
30330 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
30340 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
30350 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
30360 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30370 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
30380 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
30390 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
303a0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
303b0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
303c0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
303d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
303e0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
303f0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
30400 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
30410 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
30420 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
30430 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
30440 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
30450 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30460 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
30470 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
30490 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
304a0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
304b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
304c0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
304d0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
304e0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
304f0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30500 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
30510 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
30520 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30530 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
30540 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
30550 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
30560 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
30570 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
30580 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
30590 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
305a0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
305b0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
305c0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
305d0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
305e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
305f0 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
30600 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
30610 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
30620 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30630 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
30640 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
30650 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
30660 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
30670 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
30680 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
30690 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
306a0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
306b0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
306c0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
306d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
306e0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
306f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
30700 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
30710 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30720 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
30730 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
30740 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
30750 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
30760 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
30770 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
30780 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
30790 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
307a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
307b0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
307c0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
307d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
307e0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
307f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
30800 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
30810 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
30820 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
30830 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
30840 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
30850 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
30860 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
30870 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
30880 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
30890 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
308a0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
308b0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
308c0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
308d0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
308e0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
308f0 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
30900 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
30910 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
30920 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
30930 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
30940 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
30950 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
30960 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30970 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
30980 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
30990 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
309a0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
309b0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
309c0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
309d0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
309e0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
309f0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
30a00 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
30a10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30a20 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
30a30 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
30a40 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
30a50 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
30a60 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
30a70 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
30a80 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
30a90 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
30aa0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
30ab0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
30ac0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
30ad0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
30ae0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
30af0 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
30b00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
30b10 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
30b20 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
30b30 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
30b40 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
30b50 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
30b60 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
30b70 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
30b80 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
30b90 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
30ba0 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
30bb0 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
30bc0 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
30bd0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
30be0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
30bf0 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
30c00 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
30c10 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
30c20 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
30c30 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
30c40 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
30c50 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
30c60 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
30c70 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
30c80 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
30c90 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
30ca0 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
30cb0 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
30cc0 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
30cd0 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
30ce0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
30cf0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
30d00 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
30d10 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
30d20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
30d30 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
30d40 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
30d50 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
30d60 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
30d70 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
30d80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
30d90 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
30da0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
30db0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
30dc0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
30dd0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
30de0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
30df0 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
30e00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
30e10 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
30e20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
30e30 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
30e40 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
30e50 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
30e60 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
30e70 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
30e80 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
30e90 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
30ea0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
30eb0 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
30ec0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
30ed0 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
30ee0 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
30ef0 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
30f00 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
30f10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
30f20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
30f30 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
30f40 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
30f50 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
30f60 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
30f70 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
30f80 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
30f90 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
30fa0 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
30fb0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
30fc0 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
30fd0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
30fe0 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
30ff0 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
31000 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
31010 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
31020 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
31030 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
31040 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
31050 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
31060 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
31070 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
31080 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
31090 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
310a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
310b0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
310c0 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
310d0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
310e0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
310f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
31100 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
31110 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
31120 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
31130 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
31140 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
31150 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
31160 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
31170 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
31180 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
31190 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
311a0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
311b0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
311c0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
311d0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
311e0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
311f0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
31200 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
31210 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
31220 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
31230 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
31240 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
31250 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
31260 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
31270 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
31280 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
31290 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
312a0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
312b0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
312c0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
312d0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
312e0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
312f0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
31300 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
31310 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
31320 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
31330 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
31340 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
31350 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
31360 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
31370 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
31380 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
31390 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
313a0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
313b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
313c0 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
313d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
313e0 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
313f0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
31400 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31410 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
31420 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
31430 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
31440 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
31450 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
31460 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
31470 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
31480 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
31490 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
314a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
314b0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
314c0 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
314d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
314e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
314f0 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
31500 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
31510 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
31520 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
31530 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
31540 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
31550 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
31560 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
31570 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
31580 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
31590 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
315a0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
315b0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
315c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
315d0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
315e0 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
315f0 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
31600 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
31610 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
31620 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
31630 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
31640 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
31650 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
31660 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
31670 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
31680 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
31690 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
316a0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
316b0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
316c0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
316d0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
316e0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
316f0 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
31700 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
31710 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
31720 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
31730 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
31740 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
31750 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
31760 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
31770 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
31780 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
31790 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
317a0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
317b0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
317c0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
317d0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
317e0 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
317f0 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
31800 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
31810 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
31820 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
31830 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
31840 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
31850 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
31860 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31870 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
31880 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
31890 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
318a0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
318b0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
318c0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
318d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
318e0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
318f0 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
31900 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
31910 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
31920 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
31930 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
31940 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31950 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
31960 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
31970 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
31980 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
31990 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
319a0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
319b0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
319c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
319d0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
319e0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
319f0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
31a00 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
31a10 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
31a20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
31a30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31a40 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
31a50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
31a60 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
31a70 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
31a80 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
31a90 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
31aa0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
31ab0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
31ac0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
31ad0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
31ae0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31af0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
31b00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31b10 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31b20 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31b30 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
31b40 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
31b50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31b60 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
31b70 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
31b80 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
31b90 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
31ba0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
31bb0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
31bc0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
31bd0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
31be0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31bf0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
31c00 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
31c10 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31c30 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
31c40 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31c50 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
31c60 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
31c70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31c80 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
31c90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
31ca0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
31cb0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
31cc0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
31cd0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
31ce0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
31cf0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
31d00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31d10 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
31d20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31d30 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
31d40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31d50 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
31d60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31d70 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
31d80 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
31d90 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
31da0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
31db0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
31dc0 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
31dd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31de0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
31df0 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
31e00 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31e10 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
31e20 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
31e30 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
31e40 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
31e50 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
31e60 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
31e70 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
31e80 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
31e90 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
31ea0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
31eb0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
31ec0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
31ed0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
31ee0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31ef0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
31f00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31f10 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
31f20 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
31f30 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
31f40 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
31f50 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
31f60 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
31f70 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
31f80 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
31f90 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
31fa0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
31fb0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
31fc0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
31fd0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
31fe0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
31ff0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
32000 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
32010 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
32020 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
32030 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
32040 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
32050 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
32060 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
32070 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
32080 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
32090 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
320a0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
320b0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
320c0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
320d0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
320e0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
320f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
32100 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
32110 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
32120 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32130 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
32140 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
32150 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
32160 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
32170 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
32180 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
32190 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
321a0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
321b0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
321c0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
321d0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
321e0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
321f0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
32200 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
32210 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
32220 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
32230 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
32240 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
32250 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
32260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32270 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
32280 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
32290 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
322a0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
322b0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
322c0 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
322d0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
322e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
322f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
32300 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
32310 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
32320 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
32330 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
32340 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
32350 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
32360 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
32370 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
32380 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
32390 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
323a0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
323b0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
323c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
323d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
323e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
323f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
32400 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
32410 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
32420 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
32430 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
32440 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
32450 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
32460 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
32470 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
32480 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
32490 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
324a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
324b0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
324c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
324d0 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
324e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
324f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
32500 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32510 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
32520 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
32530 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
32540 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
32550 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
32560 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
32570 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
32580 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32590 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
325a0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
325b0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
325c0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
325d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
325e0 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
325f0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
32600 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
32610 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
32620 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
32630 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
32640 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
32650 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
32660 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
32670 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
32680 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
32690 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
326a0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
326b0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
326c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
326d0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
326e0 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
326f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
32700 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32710 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
32720 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
32730 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
32740 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
32750 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
32760 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
32770 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
32780 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
32790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
327a0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
327b0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
327c0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
327d0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
327e0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
327f0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
32800 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
32810 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
32820 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
32830 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
32840 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
32850 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
32860 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
32870 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
32880 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
32890 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
328a0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
328b0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
328c0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
328d0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
328e0 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
328f0 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
32900 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
32910 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
32920 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
32930 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
32940 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
32950 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
32960 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
32970 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
32980 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
32990 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
329a0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
329b0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
329c0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
329d0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
329e0 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
329f0 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
32a00 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
32a10 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
32a20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
32a30 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
32a40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32a50 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
32a60 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32a70 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
32a80 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
32a90 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
32aa0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
32ab0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
32ac0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
32ad0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
32ae0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
32af0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
32b00 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
32b10 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32b20 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
32b30 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
32b40 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
32b50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
32b60 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
32b70 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
32b80 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
32b90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32ba0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
32bb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32bc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
32bd0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
32be0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
32bf0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
32c00 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
32c10 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
32c20 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
32c30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32c40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
32c50 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
32c60 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
32c70 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
32c80 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
32c90 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
32ca0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
32cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32cc0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
32cd0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
32ce0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32cf0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
32d00 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
32d10 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
32d20 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
32d30 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
32d40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
32d50 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
32d60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
32d70 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
32d80 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
32d90 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
32da0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
32db0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
32dc0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
32dd0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
32de0 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
32df0 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
32e00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
32e10 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
32e20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
32e30 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
32e40 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
32e50 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
32e60 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
32e70 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
32e80 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
32e90 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
32ea0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
32eb0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
32ec0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
32ed0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
32ee0 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
32ef0 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
32f00 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
32f10 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
32f20 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
32f30 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
32f40 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
32f50 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
32f60 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
32f70 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32f80 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
32f90 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
32fa0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
32fb0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
32fc0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
32fd0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
32fe0 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
32ff0 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
33000 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
33010 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
33020 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
33030 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
33040 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
33050 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
33060 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
33070 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
33080 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
33090 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
330a0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
330b0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
330c0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
330d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
330e0 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
330f0 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
33100 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
33110 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
33120 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
33130 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33140 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
33150 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
33160 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
33170 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
33180 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33190 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
331a0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
331b0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
331c0 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
331d0 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
331e0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
331f0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
33200 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
33210 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
33220 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
33230 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
33240 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
33250 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
33260 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
33270 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
33280 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
33290 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
332a0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
332b0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
332c0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
332d0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
332e0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
332f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
33300 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
33310 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
33320 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
33330 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
33340 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
33350 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
33360 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
33370 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
33380 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
33390 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
333a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
333b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
333c0 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
333d0 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
333e0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
333f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
33400 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
33410 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
33420 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
33430 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
33440 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
33450 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
33460 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
33470 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
33480 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
33490 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
334a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
334b0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
334c0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
334d0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
334e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
334f0 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
33500 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
33510 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
33520 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
33530 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
33540 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
33550 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
33560 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
33570 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
33580 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
33590 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
335a0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
335b0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
335c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
335d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
335e0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
335f0 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
33600 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
33610 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
33620 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
33630 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
33640 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
33650 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
33660 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
33670 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
33680 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
33690 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
336a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
336b0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
336c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
336d0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
336e0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
336f0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
33700 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
33710 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
33720 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
33730 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
33740 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
33750 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
33760 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
33770 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33780 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
33790 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
337a0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
337b0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
337c0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
337d0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
337e0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
337f0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
33800 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
33810 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
33820 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33830 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
33840 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
33850 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33860 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
33870 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
33880 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
33890 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
338a0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
338b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
338c0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
338d0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
338e0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
338f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
33900 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
33910 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
33920 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
33930 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
33940 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
33950 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
33960 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
33970 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
33980 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
33990 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
339a0 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
339b0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
339c0 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
339d0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
339e0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
339f0 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
33a00 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
33a10 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
33a20 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
33a30 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
33a40 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
33a50 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
33a60 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
33a70 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
33a80 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
33a90 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
33aa0 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
33ab0 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
33ac0 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
33ad0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
33ae0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
33af0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
33b00 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
33b10 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
33b20 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
33b30 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
33b40 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
33b50 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
33b60 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
33b70 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
33b80 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
33b90 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
33ba0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
33bb0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
33bc0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
33bd0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
33be0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
33bf0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
33c00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
33c10 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
33c20 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
33c30 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
33c40 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
33c50 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
33c60 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33c70 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
33c80 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
33c90 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
33ca0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33cb0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
33cc0 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
33cd0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
33ce0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
33cf0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
33d00 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
33d10 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
33d20 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
33d30 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
33d40 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
33d50 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33d60 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
33d70 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
33d80 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
33d90 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
33da0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
33db0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33dc0 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
33dd0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
33de0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
33df0 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
33e00 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
33e10 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
33e20 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
33e30 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
33e40 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
33e50 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
33e60 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
33e70 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
33e80 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
33e90 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
33ea0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33eb0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
33ec0 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
33ed0 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
33ee0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
33ef0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
33f00 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
33f10 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
33f20 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
33f30 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
33f40 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
33f50 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
33f60 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
33f70 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
33f80 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
33f90 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
33fa0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
33fb0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
33fc0 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
33fd0 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
33fe0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
33ff0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
34000 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
34010 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
34020 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
34030 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
34040 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
34050 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
34060 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
34070 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
34080 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
34090 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
340a0 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
340b0 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
340c0 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
340d0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
340e0 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
340f0 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
34100 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
34110 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
34120 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
34130 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34140 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
34150 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
34160 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
34170 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
34180 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
34190 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
341a0 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
341b0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
341c0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
341d0 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
341e0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
341f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34200 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
34210 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
34220 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
34230 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
34240 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
34250 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
34260 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
34270 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
34280 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
34290 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
342a0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
342b0 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
342c0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
342d0 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
342e0 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
342f0 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
34300 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
34310 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
34320 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
34330 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
34340 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
34350 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
34360 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
34370 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
34380 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
34390 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
343a0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
343b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
343c0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
343d0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
343e0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
343f0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
34400 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
34410 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
34420 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
34430 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
34440 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
34450 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
34460 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
34470 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
34480 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
34490 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
344a0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
344b0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
344c0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
344d0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
344e0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
344f0 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
34500 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
34510 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
34520 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
34530 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
34540 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
34550 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
34560 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
34570 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
34580 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
34590 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
345a0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
345b0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
345c0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
345d0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
345e0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
345f0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
34600 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
34610 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
34620 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
34630 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
34640 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
34650 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
34660 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
34670 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
34680 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
34690 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
346a0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
346b0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
346c0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
346d0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
346e0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
346f0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
34700 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
34710 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
34720 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
34730 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
34740 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
34750 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
34760 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
34770 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
34780 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
34790 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
347a0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
347b0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
347c0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
347d0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
347e0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
347f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34800 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
34810 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34820 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
34830 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
34840 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
34850 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
34860 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
34870 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
34880 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
34890 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
348a0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
348b0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
348c0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
348d0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
348e0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
348f0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
34900 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
34910 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
34920 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
34930 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34940 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
34950 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
34960 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
34970 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34980 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34990 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
349a0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
349b0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
349c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
349d0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
349e0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
349f0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
34a00 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
34a10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34a20 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
34a30 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
34a40 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
34a50 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
34a60 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34a70 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
34a80 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
34a90 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
34aa0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
34ab0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
34ac0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
34ad0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
34ae0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34af0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
34b00 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34b10 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
34b20 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
34b30 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34b40 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
34b50 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
34b60 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
34b70 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
34b80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34b90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34ba0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
34bb0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34bc0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
34bd0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
34be0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
34bf0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
34c00 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
34c10 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
34c20 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
34c30 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
34c40 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
34c50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
34c60 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
34c70 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
34c80 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
34c90 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
34ca0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
34cb0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
34cc0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
34cd0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
34ce0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
34cf0 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
34d00 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
34d10 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
34d20 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34d30 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
34d40 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
34d50 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
34d60 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
34d70 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
34d80 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
34d90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34da0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
34db0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
34dc0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
34dd0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
34de0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
34df0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
34e00 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
34e10 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
34e20 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34e40 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
34e50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
34e60 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
34e70 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
34e80 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
34e90 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
34ea0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
34eb0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
34ec0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
34ed0 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
34ee0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34ef0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
34f00 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34f10 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
34f20 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
34f30 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
34f40 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
34f50 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
34f60 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
34f70 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
34f80 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
34f90 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
34fa0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
34fb0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
34fc0 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
34fd0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34fe0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
34ff0 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
35000 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
35010 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
35020 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
35030 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
35040 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
35050 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
35060 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
35070 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
35080 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
35090 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
350a0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
350b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
350c0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
350d0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
350e0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
350f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35100 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
35110 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
35120 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
35130 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
35140 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
35150 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
35160 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
35170 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
35180 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35190 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
351a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
351b0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
351c0 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
351d0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
351e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
351f0 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
35200 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35210 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
35220 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
35230 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
35240 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
35250 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35260 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
35270 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
35280 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
35290 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
352a0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
352b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
352c0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
352d0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
352e0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
352f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35300 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
35310 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
35320 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
35330 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
35340 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
35350 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35360 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
35370 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35380 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
35390 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
353a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
353b0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
353c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
353d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
353e0 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
353f0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
35400 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
35410 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
35420 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35430 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
35440 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
35450 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
35460 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
35470 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35480 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
35490 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
354a0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
354b0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
354c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
354d0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
354e0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
354f0 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
35500 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
35510 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
35520 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
35530 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
35540 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
35550 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
35560 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
35570 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
35580 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
35590 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
355a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
355b0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
355c0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
355d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
355e0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
355f0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
35600 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
35610 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
35620 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
35630 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
35640 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
35650 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35660 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
35670 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
35680 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
35690 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
356a0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
356b0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
356c0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
356d0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
356e0 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
356f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
35700 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
35710 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
35720 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
35730 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
35740 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
35750 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
35760 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
35770 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
35780 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
35790 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
357a0 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
357b0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
357c0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
357d0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
357e0 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
357f0 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
35800 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
35810 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
35820 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
35830 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
35840 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
35850 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
35860 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
35870 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
35880 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
35890 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
358a0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
358b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
358c0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
358d0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
358e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
358f0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
35900 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
35910 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
35920 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
35930 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
35940 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
35950 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
35960 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
35970 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
35980 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
35990 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
359a0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
359b0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
359c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
359d0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
359e0 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
359f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
35a00 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
35a10 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
35a20 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
35a30 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
35a40 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
35a50 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
35a60 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
35a70 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
35a80 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
35a90 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
35aa0 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
35ab0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
35ac0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
35ad0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
35ae0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
35af0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
35b00 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
35b10 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
35b20 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
35b30 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
35b40 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
35b50 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
35b60 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
35b70 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
35b80 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
35b90 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
35ba0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
35bb0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
35bc0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
35bd0 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
35be0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
35bf0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35c00 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
35c10 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
35c20 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
35c30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35c40 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35c50 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
35c60 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
35c70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
35c80 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
35c90 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
35ca0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
35cb0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
35cc0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
35cd0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
35ce0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
35cf0 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
35d00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
35d10 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
35d20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
35d30 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
35d40 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
35d50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
35d60 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
35d70 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
35d80 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
35d90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
35da0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
35db0 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
35dc0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
35dd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35de0 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
35df0 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
35e00 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
35e10 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
35e20 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
35e30 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
35e40 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
35e50 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
35e60 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
35e70 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
35e80 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
35e90 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
35ea0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
35eb0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35ec0 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
35ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
35ee0 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
35ef0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
35f00 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
35f10 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35f20 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
35f30 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
35f40 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
35f50 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
35f60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35f70 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
35f80 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
35f90 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35fa0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
35fb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
35fc0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
35fd0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35fe0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
35ff0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36000 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
36010 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36020 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
36030 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
36040 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
36050 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36060 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
36070 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
36080 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36090 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
360a0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
360b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
360c0 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
360d0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
360e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
360f0 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
36100 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
36110 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
36120 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36130 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
36140 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
36150 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36160 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36170 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
36180 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
36190 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
361a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
361b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
361c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
361d0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
361e0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
361f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36200 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
36210 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36220 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
36230 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
36240 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
36250 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
36260 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
36270 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
36280 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36290 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
362a0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
362b0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
362c0 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
362d0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
362e0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
362f0 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
36300 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
36310 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
36320 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
36330 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
36340 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
36350 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
36360 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
36370 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
36380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36390 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
363a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
363b0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
363c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
363d0 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
363e0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
363f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36400 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
36410 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36420 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
36430 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
36440 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
36450 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
36460 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36470 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
36480 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
36490 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
364a0 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
364b0 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
364c0 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
364d0 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
364e0 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
364f0 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
36500 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
36510 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
36520 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
36530 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
36540 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
36550 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
36560 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
36570 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
36580 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
36590 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
365a0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
365b0 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
365c0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
365d0 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
365e0 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
365f0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
36600 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
36610 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
36620 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
36630 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
36640 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
36650 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
36660 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
36670 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
36680 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
36690 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
366a0 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
366b0 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
366c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
366d0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
366e0 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
366f0 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
36700 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
36710 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
36720 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
36730 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
36740 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69   is an applicati
36750 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
36760 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
36770 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
36780 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
36790 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
367a0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
367b0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
367c0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
367d0 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
367e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
367f0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36800 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
36810 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36820 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
36830 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
36840 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
36850 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
36860 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
36870 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
36880 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
36890 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
368a0 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
368b0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
368c0 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
368d0 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
368e0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
368f0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
36900 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36910 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
36920 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
36930 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
36940 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
36950 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
36960 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
36970 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
36980 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
36990 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
369a0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
369b0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
369c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
369d0 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
369e0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
369f0 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
36a00 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
36a10 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
36a20 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
36a30 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
36a40 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36a50 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
36a60 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
36a70 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
36a80 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
36a90 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
36aa0 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
36ab0 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
36ac0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
36ad0 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
36ae0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
36af0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36b00 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72  on must always r
36b10 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
36b20 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
36b30 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
36b40 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
36b50 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36b60 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
36b70 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
36b80 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
36b90 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
36ba0 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
36bb0 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
36bc0 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
36bd0 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
36be0 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
36bf0 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
36c00 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
36c10 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
36c20 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
36c30 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
36c40 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
36c50 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
36c60 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
36c70 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
36c80 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
36c90 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
36ca0 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
36cb0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
36cc0 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
36cd0 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
36ce0 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
36cf0 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
36d00 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
36d10 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
36d20 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
36d30 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
36d40 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
36d50 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
36d60 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
36d70 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
36d80 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
36d90 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
36da0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
36db0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36dc0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
36dd0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
36de0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
36df0 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
36e00 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
36e10 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
36e20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
36e30 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
36e40 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36e50 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
36e60 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
36e70 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
36e80 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
36e90 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
36ea0 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
36eb0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
36ec0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
36ed0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
36ee0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
36ef0 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
36f00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
36f10 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
36f20 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
36f30 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
36f40 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
36f50 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
36f60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36f70 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
36f80 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
36f90 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
36fa0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
36fb0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36fc0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
36fd0 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
36fe0 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
36ff0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
37000 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
37010 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
37020 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
37030 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
37040 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
37050 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
37060 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
37070 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
37080 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
37090 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
370a0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
370b0 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
370c0 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
370d0 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
370e0 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
370f0 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
37100 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
37110 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
37120 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
37130 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37140 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
37150 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37160 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
37170 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37180 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
37190 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
371a0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
371b0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
371c0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
371d0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
371e0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
371f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37200 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
37210 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37220 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
37230 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
37240 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
37250 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
37260 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
37270 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
37280 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
37290 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
372a0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
372b0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
372c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
372d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
372e0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
372f0 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
37300 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
37310 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
37320 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
37330 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
37340 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
37350 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
37360 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
37370 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
37380 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
37390 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
373a0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
373b0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
373c0 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
373d0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
373e0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
373f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
37400 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
37410 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
37420 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37430 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
37440 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
37450 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
37460 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
37470 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
37480 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
37490 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
374a0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
374b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
374c0 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
374d0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
374e0 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
374f0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
37500 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
37510 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
37520 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
37530 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37540 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
37550 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
37560 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
37570 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
37580 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
37590 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
375a0 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
375b0 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
375c0 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
375d0 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
375e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
375f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
37600 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
37610 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
37620 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
37630 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
37640 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
37650 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37660 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
37670 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37680 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
37690 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
376a0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
376b0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
376c0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
376d0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
376e0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
376f0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
37700 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
37710 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
37720 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
37730 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
37740 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
37750 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
37760 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
37770 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
37780 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
37790 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
377a0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
377b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
377c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
377d0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
377e0 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
377f0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
37800 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37810 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
37820 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37830 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
37840 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37850 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
37860 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37870 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37880 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
37890 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
378a0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
378b0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
378c0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
378d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
378e0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
378f0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
37900 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
37910 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
37920 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
37930 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
37940 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
37950 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
37960 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
37970 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
37980 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
37990 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
379a0 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
379b0 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
379c0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
379d0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
379e0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
379f0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
37a00 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
37a10 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
37a20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
37a30 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
37a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37a50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
37a60 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
37a70 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
37a80 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
37a90 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
37aa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
37ab0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
37ac0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
37ad0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
37ae0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
37af0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
37b00 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
37b10 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
37b20 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  he database */. 
37b30 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
37b40 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
37b50 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
37b60 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
37b70 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
37b80 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
37b90 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
37ba0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
37bb0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
37bc0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
37bd0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
37be0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
37bf0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
37c00 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
37c10 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
37c20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
37c30 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
37c40 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
37c50 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
37c60 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
37c70 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
37c80 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
37c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
37ca0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
37cb0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
37cc0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
37cd0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
37ce0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
37cf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  ;.int sqlite3_re
37d00 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  key_v2(.  sqlite
37d10 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
37d20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
37d30 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
37d40 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  ed */.  const ch
37d50 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
37d60 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
37d70 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a  f the database *
37d80 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
37d90 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
37da0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
37db0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
37dc0 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
37dd0 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
37de0 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
37df0 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
37e00 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
37e10 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
37e20 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
37e30 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
37e40 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
37e50 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
37e60 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
37e70 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
37e80 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
37e90 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
37ea0 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
37eb0 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
37ec0 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
37ed0 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
37ee0 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
37ef0 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
37f00 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
37f10 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
37f20 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
37f30 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
37f40 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
37f50 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
37f60 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
37f70 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
37f80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
37f90 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
37fa0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
37fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
37fc0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
37fd0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
37fe0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
37ff0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
38000 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
38010 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
38020 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
38030 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
38040 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
38050 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
38060 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
38070 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
38080 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
38090 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
380a0 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
380b0 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
380c0 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
380d0 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
380e0 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
380f0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
38100 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
38110 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
38120 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
38130 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
38140 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
38150 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
38160 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
38170 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
38180 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
38190 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
381a0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
381b0 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
381c0 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
381d0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
381e0 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
381f0 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
38200 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
38210 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
38220 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
38230 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
38240 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
38250 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
38260 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
38270 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
38280 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  phs..*/.int sqli
38290 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
382a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
382b0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
382c0 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
382d0 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
382e0 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
382f0 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
38300 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
38310 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
38320 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
38330 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
38340 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
38350 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
38360 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
38370 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
38380 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
38390 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
383a0 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
383b0 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
383c0 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
383d0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
383e0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
383f0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
38400 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
38410 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
38420 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
38430 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
38440 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ry..**.** Applic
38450 61 74 69 6f 6e 73 20 61 72 65 20 73 74 72 6f 6e  ations are stron
38460 67 6c 79 20 64 69 73 63 6f 75 72 61 67 65 64 20  gly discouraged 
38470 66 72 6f 6d 20 75 73 69 6e 67 20 74 68 69 73 20  from using this 
38480 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 2e  global variable.
38490 0a 2a 2a 20 49 74 20 69 73 20 72 65 71 75 69 72  .** It is requir
384a0 65 64 20 74 6f 20 73 65 74 20 61 20 74 65 6d 70  ed to set a temp
384b0 6f 72 61 72 79 20 66 6f 6c 64 65 72 20 6f 6e 20  orary folder on 
384c0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
384d0 28 57 69 6e 52 54 29 2e 0a 2a 2a 20 42 75 74 20  (WinRT)..** But 
384e0 66 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 70 6c  for all other pl
384f0 61 74 66 6f 72 6d 73 2c 20 69 74 20 69 73 20 68  atforms, it is h
38500 69 67 68 6c 79 20 72 65 63 6f 6d 6d 65 6e 64 65  ighly recommende
38510 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
38520 6f 6e 73 0a 2a 2a 20 6e 65 69 74 68 65 72 20 72  ons.** neither r
38530 65 61 64 20 6e 6f 72 20 77 72 69 74 65 20 74 68  ead nor write th
38540 69 73 20 76 61 72 69 61 62 6c 65 2e 20 20 54 68  is variable.  Th
38550 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
38560 6c 65 20 69 73 20 61 20 72 65 6c 69 63 0a 2a 2a  le is a relic.**
38570 20 74 68 61 74 20 65 78 69 73 74 73 20 66 6f 72   that exists for
38580 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
38590 74 69 62 69 6c 69 74 79 20 6f 66 20 6c 65 67 61  tibility of lega
385a0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
385b0 61 6e 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  and should.** be
385c0 20 61 76 6f 69 64 65 64 20 69 6e 20 6e 65 77 20   avoided in new 
385d0 70 72 6f 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20  projects..**.** 
385e0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
385f0 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
38600 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
38610 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
38620 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
38630 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
38640 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
38650 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
38660 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
38670 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38680 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
38690 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
386a0 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
386b0 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
386c0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
386d0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
386e0 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
386f0 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
38700 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
38710 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
38720 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
38730 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
38740 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
38750 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
38760 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
38770 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
38780 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
38790 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
387a0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
387b0 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
387c0 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
387d0 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
387e0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
387f0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
38800 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
38810 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
38820 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
38830 63 74 6f 72 79 20 70 72 61 67 6d 61