/ Hex Artifact Content
Login

Artifact 44b761ddf5362581617d08457f11ee582eb103a2:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
4090: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63  t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69  rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5950: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5970: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5990: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
59a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
59b0: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
5a20: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a60: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
5ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ae0: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
5af0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b00: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
5b10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
5b30: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
5b40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
5b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b70: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
5b80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b90: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5ba0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5bb0: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
5bc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5bd0: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
5be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5bf0: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
5c00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5c10: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
5c20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
5c40: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5c50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
5c60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c70: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5c80: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
5c90: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
5ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cb0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5cc0: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
5cd0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
5ce0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cf0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
5d00: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
5d10: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
5d20: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5d30: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5d40: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5d50: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5d60: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5d70: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5d80: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5d90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5da0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5db0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5dc0: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5dd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5df0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5e00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e10: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5e20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e30: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5e40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5e50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e60: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5e70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e80: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5e90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ea0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5eb0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5ec0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5ed0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5ee0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f00: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5f10: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5f20: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
5f30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
5f50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5f60: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5f70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f80: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5f90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5fa0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5fb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fc0: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5fd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5fe0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5ff0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6010: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6020: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6030: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6040: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6050: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6060: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
6070: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6080: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
60b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
60c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60e0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
60f0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6100: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6130: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6140: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
6170: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
6180: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6190: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61a0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
61b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
61c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61e0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
61f0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6200: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6210: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6220: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6230: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6240: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6250: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
6280: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
6290: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
62b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62c0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
62d0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
62e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6300: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6310: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6320: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6330: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6340: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6350: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6360: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
6370: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
6380: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6390: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
63c0: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
63d0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
63e0: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
63f0: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6400: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6410: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6420: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6430: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6440: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
6450: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
6460: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
6470: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
6480: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
6490: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
64a0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
64b0: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
64c0: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
64d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
64e0: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
64f0: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6500: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6510: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6520: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6530: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6540: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6550: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6560: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
6570: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
6580: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
6590: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
65a0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
65b0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
65c0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
65d0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
65e0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
65f0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6600: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6610: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6620: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6630: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6640: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6650: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6660: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
6670: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
6680: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
6690: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
66a0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
66b0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
66c0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
66d0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
66e0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
66f0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6700: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6710: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6720: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6730: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6740: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6750: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
6760: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
6770: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
6780: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
6790: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
67a0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
67b0: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
67c0: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
67d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
67e0: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
67f0: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6800: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6810: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6820: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6830: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6840: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
6850: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
6860: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6870: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
6880: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
6890: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e   that a file can
68a0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77  not be deleted w
68b0: 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a  hen open.  The.*
68c0: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  * SQLITE_IOCAP_I
68d0: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e  MMUTABLE flag in
68e0: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
68f0: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72   file is on.** r
6900: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61  ead-only media a
6910: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  nd cannot be cha
6920: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f  nged even by pro
6930: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65  cesses with.** e
6940: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67  levated privileg
6950: 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  es..*/.#define S
6960: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6970: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
6980: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
6990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69a0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
69b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69c0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
69d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69e0: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
69f0: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
6a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a10: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
6a20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6a30: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
6a40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6a50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6a60: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
6a70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a80: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
6a90: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
6aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ab0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
6ac0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ad0: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
6ae0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6af0: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
6b00: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
6b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b20: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
6b30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b40: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
6b50: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6b60: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
6b70: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
6b80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b90: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
6ba0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6bb0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
6bc0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
6bd0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
6be0: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
6bf0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c00: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
6c10: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30  ITE    0x0000100
6c20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c30: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
6c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6c50: 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00002000../*.** 
6c60: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
6c70: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
6c80: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6c90: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
6ca0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6cb0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
6cc0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
6cd0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
6ce0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6cf0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6d00: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6d10: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6d20: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
6d30: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
6d40: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
6d50: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
6d60: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
6d70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6d80: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6d90: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6da0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6db0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6dc0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6dd0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6de0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6df0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6e00: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6e10: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6e20: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6e30: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6e40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6e50: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
6e60: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6e70: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6e80: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6e90: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6ea0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6eb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6ec0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6ed0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6ee0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6ef0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6f00: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6f10: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6f20: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6f30: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6f40: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
6f50: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6f60: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
6f70: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
6f80: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6f90: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6fa0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6fb0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6fc0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6fd0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6fe0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6ff0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
7000: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7010: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
7020: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7030: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7040: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7050: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7060: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7070: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
7080: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7090: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
70a0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
70b0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
70c0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
70d0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
70e0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
70f0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
7100: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
7110: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7120: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7130: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7140: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7150: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7160: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7170: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
7180: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
7190: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
71a0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
71b0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
71c0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
71d0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
71e0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
71f0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
7200: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
7210: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7220: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7230: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7240: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7250: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7260: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7270: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7280: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7290: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
72a0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
72b0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
72c0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
72d0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
72e0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
72f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7300: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
7310: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7320: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7330: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7340: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7350: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7360: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7370: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7380: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7390: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
73a0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
73b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
73c0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
73d0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
73e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
73f0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7400: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7410: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7420: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7430: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7440: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7450: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7460: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7470: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7480: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7490: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
74a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
74b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
74c0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
74d0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
74e0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
74f0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7500: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7510: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7520: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7530: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7540: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7550: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7560: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7570: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7580: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7590: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
75a0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
75b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
75c0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
75d0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
75e0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
75f0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7600: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7610: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7620: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7640: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7650: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7660: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7670: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7680: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7690: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
76a0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
76b0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
76c0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
76d0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
76e0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
76f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7700: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7710: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7720: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7730: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7740: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7750: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7760: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7770: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7780: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7790: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
77a0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
77b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
77c0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
77d0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
77e0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
77f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7800: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7810: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7820: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7830: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7840: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7850: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7860: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7870: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7880: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7890: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
78a0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
78b0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
78c0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
78d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
78e0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
78f0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7900: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7910: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7920: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7930: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7940: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7950: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7960: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7970: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7980: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7990: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
79a0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
79b0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
79c0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
79d0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
79e0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
79f0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
7a00: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
7a10: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7a20: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7a30: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
7a40: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
7a50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7a60: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
7a70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
7a80: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
7a90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
7aa0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
7ab0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7ac0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
7ad0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
7ae0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
7af0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
7b00: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7b10: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
7b20: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
7b30: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
7b40: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
7b50: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
7b60: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
7b70: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
7b80: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
7b90: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
7ba0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
7bb0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
7bc0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
7bd0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
7be0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
7bf0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
7c00: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
7c10: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
7c20: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
7c30: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
7c40: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
7c50: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
7c60: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
7c70: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
7c80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7c90: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
7ca0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
7cb0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
7cc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7cd0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
7ce0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
7cf0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7d00: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7d10: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7d20: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
7d30: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
7d40: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
7d50: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
7d60: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
7d70: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
7d80: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7d90: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7da0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7db0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7dc0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7dd0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7de0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7df0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7e00: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7e10: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7e20: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
7e30: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
7e40: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
7e50: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
7e60: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
7e70: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
7e80: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7e90: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7ea0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7eb0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7ec0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7ed0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7ee0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7ef0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7f00: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7f10: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7f20: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7f30: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7f40: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
7f50: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7f60: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7f70: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7f80: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7f90: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7fa0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7fb0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7fc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7fd0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7fe0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7ff0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
8000: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
8010: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
8020: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
8030: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
8040: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
8050: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
8060: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
8070: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
8080: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
8090: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
80a0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
80b0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
80c0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
80d0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
80e0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
80f0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
8100: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
8110: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
8120: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
8130: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
8140: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
8150: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8170: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
8180: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8190: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
81a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81b0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
81c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81d0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
81e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81f0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
8200: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8210: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
8220: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8230: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8240: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8250: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8260: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8270: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
8280: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8290: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
82a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
82b0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
82c0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
82d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
82e0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
82f0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
8300: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
8310: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
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 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8340: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8350: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8360: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8370: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8380: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8390: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
83a0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
83b0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
83c0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
83d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
83e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
83f0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
8400: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
8410: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8420: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8430: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8440: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8450: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8460: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8470: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8480: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8490: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
84a0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
84b0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
84c0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
84d0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
84e0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
84f0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
8500: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
8510: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8520: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8530: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8540: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8550: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8560: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8570: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8580: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8590: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
85a0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
85b0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
85c0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
85d0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
85e0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
85f0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
8600: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
8610: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8620: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8630: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8640: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8650: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8660: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8670: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8680: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8690: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
86a0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
86b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
86c0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
86d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
86e0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
86f0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
8700: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
8710: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8720: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8730: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8740: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8750: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8760: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8770: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8780: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8790: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
87a0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
87b0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
87c0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
87d0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
87e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
87f0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
8800: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8810: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8820: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8830: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8840: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8850: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8860: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8870: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8880: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8890: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
88a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
88b0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
88c0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
88d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
88e0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
88f0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8900: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8910: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8920: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8930: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8940: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8950: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8960: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8970: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8980: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8990: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
89a0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
89b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
89c0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
89d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
89e0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
89f0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8a00: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8a10: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
8a20: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
8a30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8a40: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8a50: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8a60: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
8a70: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8a80: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8a90: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
8aa0: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
8ab0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8ac0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8ad0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
8ae0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
8af0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
8b00: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
8b10: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
8b20: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
8b30: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8b40: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
8b50: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8b60: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8b70: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8b80: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8b90: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8ba0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
8bb0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
8bc0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8bd0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
8be0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
8bf0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8c00: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8c10: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8c20: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8c30: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8c40: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8c50: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8c60: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8c70: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8c80: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8c90: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8ca0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8cb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8cc0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8cd0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8ce0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8cf0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8d00: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8d10: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8d20: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8d30: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8d40: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8d50: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
8d60: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
8d70: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
8d80: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
8d90: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e  defined..** <ul>
8da0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8db0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8dc0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8dd0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8de0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
8df0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
8e00: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
8e10: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
8e20: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
8e30: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
8e40: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
8e50: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
8e60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
8e70: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
8e80: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
8e90: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
8ea0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
8eb0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
8ec0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8ed0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8ee0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8ef0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8f00: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8f10: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8f20: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8f30: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8f40: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8f50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8f60: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a  TL_CHUNK_SIZE]].
8f70: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8f80: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8f90: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8fa0: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20  to request that 
8fb0: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e  the VFS.** exten
8fc0: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73  ds and truncates
8fd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8fe0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20  le in chunks of 
8ff0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64  a size specified
9000: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e  .** by the user.
9010: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
9020: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
9030: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9040: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e   should .** poin
9050: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  t to an integer 
9060: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61  (type int) conta
9070: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68  ining the new ch
9080: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a  unk-size to use.
9090: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e  ** for the nomin
90a0: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41  ated database. A
90b0: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61  llocating databa
90c0: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e  se file space in
90d0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73   large.** chunks
90e0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74   (say 1MB at a t
90f0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65  ime), may reduce
9100: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61   file-system fra
9110: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a  gmentation and.*
9120: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  * improve perfor
9130: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79  mance on some sy
9140: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  stems..**.** <li
9150: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9160: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  FILE_POINTER]].*
9170: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9180: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
9190: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
91a0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
91b0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
91c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
91d0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
91e0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
91f0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
9200: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
9210: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9220: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
9230: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
9240: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
9250: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  rmation..**.** <
9260: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9270: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
9280: 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e  .** No longer in
9290: 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e   use..**.** <li>
92a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
92b0: 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  YNC]].** The [SQ
92c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
92d0: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
92e0: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
92f0: 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a  by SQLite and.**
9300: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
9310: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
9320: 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65  ore the xSync me
9330: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
9340: 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65  on a.** database
9350: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
9360: 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79  . Or, if the xSy
9370: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74  nc method is not
9380: 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63   invoked .** bec
9390: 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61  ause the user ha
93a0: 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c  s configured SQL
93b0: 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52  ite with .** [PR
93c0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
93d0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
93e0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73  onous=OFF] it is
93f0: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63   invoked in plac
9400: 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79  e .** of the xSy
9410: 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f  nc method. In mo
9420: 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f  st cases, the po
9430: 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70  inter argument p
9440: 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  assed with.** th
9450: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
9460: 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72  is NULL. However
9470: 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  , if the databas
9480: 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20  e file is being 
9490: 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72  synced.** as par
94a0: 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74  t of a multi-dat
94b0: 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68  abase commit, th
94c0: 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  e argument point
94d0: 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69  s to a nul-termi
94e0: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
94f0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74  containing the t
9500: 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74  ransactions mast
9510: 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  er-journal file 
9520: 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74  name. VFSes that
9530: 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64   .** do not need
9540: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f   this signal sho
9550: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
9560: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
9570: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a   Applications .*
9580: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  * should not cal
9590: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
95a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
95b0: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
95c0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20  oing so may .** 
95d0: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
95e0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
95f0: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9600: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9610: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9620: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9630: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a  MMIT_PHASETWO]].
9640: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9650: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
9660: 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETWO] opcode is 
9670: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9680: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a  ally by SQLite.*
9690: 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68  * and sent to th
96a0: 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72  e VFS after a tr
96b0: 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65  ansaction has be
96c0: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d  en committed imm
96d0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20  ediately.** but 
96e0: 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62  before the datab
96f0: 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e  ase is unlocked.
9700: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e   VFSes that do n
9710: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9720: 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69  nal.** should si
9730: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9740: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
9750: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
9760: 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  ot call.** [sqli
9770: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9780: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9790: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
97a0: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
97b0: 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f   .** operation o
97c0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
97d0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
97e0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
97f0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9800: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9810: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
9820: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9830: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
9840: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9850: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
9860: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
9870: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
9880: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
9890: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
98a0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
98b0: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
98c0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
98d0: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
98e0: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
98f0: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
9900: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
9910: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
9920: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
9930: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
9940: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
9950: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
9960: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
9970: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
9980: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
9990: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
99a0: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
99b0: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
99c0: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
99d0: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
99e0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
99f0: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
9a00: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
9a10: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
9a20: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
9a30: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
9a40: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
9a50: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
9a60: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
9a70: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
9a80: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
9a90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9aa0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
9ab0: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
9ac0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
9ad0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9ae0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
9af0: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
9b00: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
9b10: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
9b20: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
9b30: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
9b40: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
9b50: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
9b60: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
9b70: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
9b80: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
9b90: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
9ba0: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
9bb0: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
9bc0: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
9bd0: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
9be0: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
9bf0: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
9c00: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
9c10: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
9c20: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
9c30: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
9c40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9c50: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
9c60: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
9c70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9c80: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
9c90: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9ca0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9cb0: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
9cc0: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
9cd0: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
9ce0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
9cf0: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
9d00: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
9d10: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9d20: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
9d30: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
9d40: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
9d50: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
9d60: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
9d70: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
9d80: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
9d90: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
9da0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
9db0: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
9dc0: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
9dd0: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
9de0: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
9df0: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
9e00: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
9e10: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
9e20: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
9e30: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
9e40: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
9e50: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
9e60: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
9e70: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
9e80: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
9e90: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
9ea0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
9eb0: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
9ec0: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
9ed0: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
9ee0: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
9ef0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
9f00: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9f10: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
9f20: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
9f30: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
9f40: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
9f50: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
9f60: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
9f70: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
9f80: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
9f90: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
9fa0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9fb0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9fc0: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9fd0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9fe0: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
9ff0: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
a000: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a010: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a020: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a030: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a040: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a050: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a060: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a070: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a080: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a090: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a0a0: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a0b0: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a0c0: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a0d0: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a0e0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a0f0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a100: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a110: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a120: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a130: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a140: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a150: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a160: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a170: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a180: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a190: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a1a0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a1b0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a1c0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a1d0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a1e0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a1f0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a200: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a210: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a220: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a230: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a240: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a250: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a260: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a270: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
a280: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a290: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
a2a0: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
a2b0: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
a2c0: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
a2d0: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
a2e0: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
a2f0: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
a300: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
a310: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
a320: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
a330: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
a340: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
a350: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
a360: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
a370: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
a380: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a390: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
a3a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a3b0: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
a3c0: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
a3d0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
a3e0: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
a3f0: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
a400: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
a410: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
a420: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
a430: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
a440: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
a450: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
a460: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
a470: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
a480: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
a490: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
a4a0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a4b0: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
a4c0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a4d0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
a4e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
a4f0: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
a500: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
a510: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
a520: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
a530: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
a540: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
a550: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
a560: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
a570: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
a580: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
a590: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
a5a0: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
a5b0: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
a5c0: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
a5d0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
a5e0: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
a5f0: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
a600: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
a610: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
a620: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
a630: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
a640: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
a650: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a660: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
a670: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
a680: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
a690: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
a6a0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
a6b0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a6c0: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
a6d0: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
a6e0: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
a6f0: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
a700: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a710: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
a720: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
a730: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
a740: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
a750: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a760: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a770: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
a780: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
a790: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
a7a0: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
a7b0: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
a7c0: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
a7d0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
a7e0: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
a7f0: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
a800: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
a810: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
a820: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
a830: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
a840: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
a850: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
a860: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a870: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
a880: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
a890: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
a8a0: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
a8b0: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
a8c0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
a8d0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
a8e0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
a8f0: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
a900: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
a910: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
a920: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
a930: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
a940: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
a950: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
a960: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
a970: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
a980: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a990: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a9a0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
a9b0: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
a9c0: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
a9d0: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
a9e0: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a9f0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
aa00: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aa10: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
aa20: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
aa30: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
aa40: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
aa50: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
aa60: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
aa70: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
aa80: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
aa90: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
aaa0: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  nt.  ^If the [SQ
aab0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aac0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
aad0: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
aae0: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
aaf0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
ab00: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
ab10: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
ab20: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
ab30: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
ab40: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
ab50: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
ab60: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
ab70: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
ab80: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
ab90: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
aba0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
abb0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
abc0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
abd0: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
abe0: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
abf0: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
ac00: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
ac10: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
ac20: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
ac30: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
ac40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
ac50: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
ac60: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
ac70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
ac80: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d  ANDLER].** file-
ac90: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
aca0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
acb0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
acc0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
acd0: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
ace0: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
acf0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
ad00: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
ad10: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
ad20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
ad30: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
ad40: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
ad50: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
ad60: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
ad70: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
ad80: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
ad90: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
ada0: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
adb0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
adc0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
add0: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
ade0: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
adf0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
ae00: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
ae10: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
ae20: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
ae30: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
ae40: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
ae50: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
ae60: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
ae70: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
ae80: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
ae90: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
aea0: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
aeb0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
aec0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
aed0: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
aee0: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
aef0: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
af00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
af10: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
af20: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
af30: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
af40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af50: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66  _TEMPFILENAME] f
af60: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74  ile-control.** t
af70: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65  o have SQLite ge
af80: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70  nerate a.** temp
af90: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75  orary filename u
afa0: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
afb0: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20  gorithm that is 
afc0: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65  followed to gene
afd0: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  rate.** temporar
afe0: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20  y filenames for 
aff0: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20  TEMP tables and 
b000: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75  other internal u
b010: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67  ses.  The.** arg
b020: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
b030: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77  a char** which w
b040: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69  ill be filled wi
b050: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  th the filename.
b060: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ** written into 
b070: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
b080: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
b090: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61  lloc()].  The ca
b0a0: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69  ller should.** i
b0b0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
b0c0: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65  ree()] on the re
b0d0: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20  sult to avoid a 
b0e0: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a  memory leak..**.
b0f0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b100: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b110: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b120: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b130: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b140: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
b150: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
b160: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b170: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
b180: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
b190: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
b1a0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b1b0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
b1c0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
b1d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
b1e0: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
b1f0: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
b200: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
b210: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
b220: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
b230: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
b240: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
b250: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
b260: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
b270: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61  ged if.** the va
b280: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70  lue originally p
b290: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67  ointed to is neg
b2a0: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68  ative, and so th
b2b0: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20  e current limit 
b2c0: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69  .** can be queri
b2d0: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e  ed by passing in
b2e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b2f0: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e  negative number.
b300: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63    This.** file-c
b310: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69  ontrol is used i
b320: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70  nternally to imp
b330: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d  lement [PRAGMA m
b340: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a  map_size]..**.**
b350: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b360: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54  NTL_TRACE]].** T
b370: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b380: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e  _TRACE] file con
b390: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64  trol provides ad
b3a0: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  visory informati
b3b0: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53  on.** to the VFS
b3c0: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20   about what the 
b3d0: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66  higher layers of
b3e0: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63   the SQLite stac
b3f0: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20  k are doing..** 
b400: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
b410: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d  l is used by som
b420: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74  e VFS activity t
b430: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a  racing [shims]..
b440: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b450: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  is a zero-termin
b460: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69  ated string.  Hi
b470: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74  gher layers in t
b480: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61  he.** SQLite sta
b490: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20  ck may generate 
b4a0: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69  instances of thi
b4b0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
b4c0: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  f.** the [SQLITE
b4d0: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  _USE_FCNTL_TRACE
b4e0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
b4f0: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
b500: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b510: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
b520: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  OVED]].** The [S
b530: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
b540: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74  MOVED] file cont
b550: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
b560: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
b570: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
b580: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74  n integer and it
b590: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61   writes a boolea
b5a0: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  n into that inte
b5b0: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a  ger depending.**
b5c0: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e   on whether or n
b5d0: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20  ot the file has 
b5e0: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f  been renamed, mo
b5f0: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ved, or deleted 
b600: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20  since it.** was 
b610: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a  first opened..**
b620: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b630: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
b640: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
b650: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
b660: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
b670: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
b680: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
b690: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
b6a0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
b6b0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
b6c0: 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68   swap the file h
b6d0: 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f  andle with the o
b6e0: 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ne.** pointed to
b6f0: 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67   by the pArg arg
b700: 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70  ument.  This cap
b710: 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20  ability is used 
b720: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a  during testing.*
b730: 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  * and only needs
b740: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
b750: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
b760: 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  T is defined..**
b770: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
b780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b790: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
b7a0: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
b7b0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
b7c0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
b7d0: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
b7e0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
b7f0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
b800: 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
b810: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
b820: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
b830: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
b840: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
b850: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
b860: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
b870: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
b880: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
b890: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
b8a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
b8b0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
b8c0: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
b8d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
b8e0: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
b8f0: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
b900: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b910: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
b920: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
b930: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
b940: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
b950: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
b960: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
b970: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
b980: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b990: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
b9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
b9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9c0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
b9d0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
b9e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b9f0: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
ba00: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
ba10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ba20: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
ba30: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
ba40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ba50: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
ba60: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
ba70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ba80: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
ba90: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
baa0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bab0: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
bac0: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
bad0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bae0: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
baf0: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e         20.#defin
bb00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
bb10: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
bb20: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65        21.#define
bb30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
bb40: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20  MMIT_PHASETWO   
bb50: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20       22.#define 
bb60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bb70: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_SET_HANDLE   
bb80: 20 20 20 20 32 33 0a 0a 2f 2a 0a 2a 2a 20 43 41      23../*.** CA
bb90: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
bba0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
bbb0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
bbc0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
bbd0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
bbe0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
bbf0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
bc00: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
bc10: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
bc20: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
bc30: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
bc40: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
bc50: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
bc60: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
bc70: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
bc80: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
bc90: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
bca0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
bcb0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
bcc0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
bcd0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
bce0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
bcf0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
bd00: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
bd10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
bd20: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
bd30: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
bd40: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
bd50: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
bd60: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
bd70: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
bd80: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
bd90: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
bda0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
bdb0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
bdc0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
bdd0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
bde0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
bdf0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
be00: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
be10: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
be20: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
be30: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
be40: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
be50: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
be60: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
be70: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
be80: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
be90: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
bea0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
beb0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
bec0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
bed0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
bee0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
bef0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
bf00: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
bf10: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
bf20: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
bf30: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
bf40: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
bf50: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
bf60: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
bf70: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
bf80: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
bf90: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
bfa0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
bfb0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
bfc0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
bfd0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
bfe0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
bff0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
c000: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
c010: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
c020: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
c030: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
c040: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
c050: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
c060: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
c070: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
c080: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
c090: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
c0a0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
c0b0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c0c0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
c0d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
c0e0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
c0f0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
c100: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
c110: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
c120: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
c130: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
c140: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
c150: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
c160: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
c170: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
c180: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
c190: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
c1a0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
c1b0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
c1c0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
c1d0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
c1e0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
c1f0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
c200: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
c210: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
c220: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
c230: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
c240: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
c250: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
c260: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
c270: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
c280: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c290: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
c2a0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
c2b0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
c2c0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
c2d0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
c2e0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
c2f0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
c300: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
c310: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
c320: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
c330: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
c340: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
c350: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
c360: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
c370: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
c380: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c390: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c3a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
c3b0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
c3c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
c3d0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
c3e0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
c3f0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
c400: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
c410: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
c420: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
c430: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
c440: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
c450: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
c460: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
c470: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
c480: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
c490: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
c4a0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
c4b0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
c4c0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
c4d0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
c4e0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
c4f0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
c500: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
c510: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
c520: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
c530: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
c540: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
c550: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
c560: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
c570: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
c580: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
c590: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
c5a0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
c5b0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
c5c0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
c5d0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c5e0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
c5f0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
c600: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
c610: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
c620: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
c630: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
c640: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
c650: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c660: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
c670: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
c680: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
c690: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
c6a0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
c6b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c6c0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
c6d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c6e0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
c6f0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
c700: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
c710: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
c720: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
c730: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
c740: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
c750: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
c760: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
c770: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
c780: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
c790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
c7a0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
c7b0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
c7c0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
c7d0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
c7e0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
c7f0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
c800: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
c810: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
c820: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
c830: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
c840: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
c850: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
c860: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
c870: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
c880: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
c890: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
c8a0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
c8b0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
c8c0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c8d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
c8e0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
c8f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c900: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
c910: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c920: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
c930: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c940: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
c950: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c960: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
c970: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c980: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
c990: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c9a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
c9b0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
c9c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c9d0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
c9e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
c9f0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
ca00: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
ca10: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
ca20: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
ca30: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
ca40: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
ca50: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
ca60: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
ca70: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
ca80: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
ca90: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
caa0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
cab0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
cac0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
cad0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
cae0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
caf0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
cb00: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
cb10: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
cb20: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
cb30: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
cb40: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
cb50: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
cb60: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
cb70: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
cb80: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
cb90: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
cba0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
cbb0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
cbc0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
cbd0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
cbe0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
cbf0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
cc00: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
cc10: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
cc20: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
cc30: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
cc40: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
cc50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
cc60: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
cc70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
cc80: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
cc90: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
cca0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
ccb0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
ccc0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
ccd0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
cce0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
ccf0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
cd00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
cd10: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
cd20: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
cd30: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
cd40: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
cd50: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
cd60: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
cd70: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
cd80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
cd90: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
cda0: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
cdb0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
cdc0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
cdd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
cde0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
cdf0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
ce00: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
ce10: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
ce20: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
ce30: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
ce40: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
ce50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
ce60: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
ce70: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
ce80: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
ce90: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
cea0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
ceb0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
cec0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
ced0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
cee0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
cef0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
cf00: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
cf10: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
cf20: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
cf30: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
cf40: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
cf50: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
cf60: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
cf70: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
cf80: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
cf90: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
cfa0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
cfb0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
cfc0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
cfd0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
cfe0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
cff0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d000: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
d010: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
d020: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
d030: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
d040: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
d050: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
d060: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
d070: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
d080: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
d090: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
d0a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
d0b0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
d0c0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
d0d0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
d0e0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
d0f0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
d100: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
d110: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d120: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
d130: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
d140: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
d150: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
d160: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
d170: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
d180: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
d190: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
d1a0: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
d1b0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d1c0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
d1d0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
d1e0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
d1f0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
d200: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
d210: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
d220: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
d230: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
d240: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
d250: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d260: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
d270: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
d280: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
d290: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
d2a0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
d2b0: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
d2c0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
d2d0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
d2e0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
d2f0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
d300: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
d310: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
d320: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
d330: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
d340: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
d350: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d360: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
d370: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
d380: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
d390: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d3a0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
d3b0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
d3c0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
d3d0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
d3e0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
d3f0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
d400: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
d410: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
d420: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
d430: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
d440: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
d450: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
d460: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
d470: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
d480: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
d490: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
d4a0: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
d4b0: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
d4c0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
d4d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
d4e0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
d4f0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
d500: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
d510: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
d520: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
d530: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
d540: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
d550: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
d560: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
d570: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
d580: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
d590: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
d5a0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
d5b0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
d5c0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
d5d0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
d5e0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
d5f0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
d600: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
d610: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
d620: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
d630: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
d640: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
d650: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
d660: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
d670: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
d680: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
d690: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
d6a0: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
d6b0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
d6c0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
d6d0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
d6e0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d6f0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
d700: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
d710: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
d720: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
d730: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
d740: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
d750: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
d760: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
d770: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
d780: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
d790: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d7a0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
d7b0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
d7c0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
d7d0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
d7e0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
d7f0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
d800: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
d810: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
d820: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
d830: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
d840: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
d850: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
d860: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d870: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
d880: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
d890: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
d8a0: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
d8b0: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
d8c0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
d8d0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
d8e0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
d8f0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
d900: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
d910: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
d920: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
d930: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
d940: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
d950: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
d960: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
d970: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
d980: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
d990: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
d9a0: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
d9b0: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
d9c0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
d9d0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
d9e0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
d9f0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
da00: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
da10: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
da20: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
da30: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
da40: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
da50: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
da60: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
da70: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
da80: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
da90: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
daa0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
dab0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
dac0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
dad0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
dae0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
daf0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
db00: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
db10: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
db20: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
db30: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
db40: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
db50: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
db60: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
db70: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
db80: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
db90: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
dba0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
dbb0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
dbc0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
dbd0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
dbe0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
dbf0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
dc00: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
dc10: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
dc20: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
dc30: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
dc40: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
dc50: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
dc60: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
dc70: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
dc80: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
dc90: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
dca0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
dcb0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
dcc0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
dcd0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
dce0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
dcf0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
dd00: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
dd10: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
dd20: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
dd30: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
dd40: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
dd50: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
dd60: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
dd70: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
dd80: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
dd90: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
dda0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
ddb0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ddc0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ddd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
dde0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
ddf0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
de00: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
de10: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
de20: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
de30: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
de40: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
de50: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
de60: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
de70: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
de80: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
de90: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
dea0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
deb0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dec0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
ded0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
dee0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
def0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
df00: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
df10: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
df20: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
df30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
df40: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
df50: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
df60: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
df70: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
df80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
df90: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
dfa0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
dfb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
dfc0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
dfd0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
dfe0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
dff0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
e000: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
e010: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e020: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
e030: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
e040: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
e050: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
e060: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
e070: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
e080: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
e090: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e0a0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e0b0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
e0c0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e0d0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
e0e0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
e0f0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
e100: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
e110: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
e120: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
e130: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
e140: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
e150: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
e160: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e170: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e180: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
e190: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e1a0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
e1b0: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
e1c0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
e1d0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
e1e0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
e1f0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e200: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e210: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
e220: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
e230: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
e240: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
e250: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e260: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e270: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
e280: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
e290: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e2a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e2b0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
e2c0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e2d0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e2e0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
e2f0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
e300: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e310: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
e320: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
e330: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
e340: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
e350: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
e360: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
e370: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
e380: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
e390: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e3a0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
e3b0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
e3c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
e3d0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
e3e0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
e3f0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
e400: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
e410: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
e420: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
e430: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
e440: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
e450: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
e460: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e470: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
e480: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e490: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
e4a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e4b0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
e4c0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e4d0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
e4e0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e4f0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
e500: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e510: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e520: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
e530: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
e540: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
e550: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
e560: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
e570: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
e580: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
e590: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
e5a0: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
e5b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
e5c0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
e5d0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
e5e0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
e5f0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
e600: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
e610: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
e620: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
e630: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
e640: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
e650: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e660: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
e670: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e680: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e690: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
e6a0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
e6b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
e6c0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
e6d0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
e6e0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
e6f0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
e700: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
e710: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
e720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e730: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
e740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e750: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
e760: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
e770: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
e780: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
e790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e7a0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
e7b0: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
e7c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e7d0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
e7e0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
e7f0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
e800: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
e810: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
e820: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
e830: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
e840: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
e850: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
e860: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
e870: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
e880: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
e890: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
e8a0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
e8b0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
e8c0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
e8d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
e8e0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
e8f0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
e900: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e910: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
e920: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
e930: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e940: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
e950: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
e960: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e970: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
e980: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
e990: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
e9a0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
e9b0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
e9c0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
e9d0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
e9e0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
e9f0: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
ea00: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
ea10: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
ea20: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
ea30: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
ea40: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
ea50: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
ea60: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
ea70: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
ea80: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
ea90: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
eaa0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
eab0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
eac0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
ead0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
eae0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
eaf0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
eb00: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
eb10: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
eb20: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
eb30: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
eb40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
eb50: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
eb60: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
eb70: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
eb80: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
eb90: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
eba0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
ebb0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
ebc0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
ebd0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
ebe0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
ebf0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
ec00: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
ec10: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
ec20: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
ec30: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
ec40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
ec50: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
ec60: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
ec70: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
ec80: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
ec90: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
eca0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ecb0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
ecc0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
ecd0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
ece0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
ecf0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
ed00: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
ed10: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
ed20: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
ed30: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
ed40: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
ed50: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
ed60: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
ed70: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
ed80: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
ed90: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
eda0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
edb0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
edc0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
edd0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
ede0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
edf0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
ee00: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
ee10: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
ee20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ee30: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
ee40: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
ee50: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
ee60: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
ee70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
ee80: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
ee90: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
eea0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
eeb0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
eec0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
eed0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
eee0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
eef0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
ef00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ef10: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
ef20: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
ef30: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
ef40: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
ef50: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
ef60: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
ef70: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
ef80: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
ef90: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
efa0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
efb0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
efc0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
efd0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
efe0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
eff0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
f000: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
f010: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
f020: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
f030: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
f040: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f050: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
f060: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
f070: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
f080: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
f090: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
f0a0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
f0b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f0c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f0d0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
f0e0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
f0f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
f100: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
f110: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f120: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
f130: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
f140: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
f150: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
f160: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
f170: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
f180: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
f190: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
f1a0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
f1b0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
f1c0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
f1d0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
f1e0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
f1f0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
f200: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
f210: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
f220: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f230: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
f240: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
f250: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
f260: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
f270: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
f280: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f290: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f2a0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
f2b0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f2c0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
f2d0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
f2e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f2f0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
f300: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
f310: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
f320: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
f330: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
f340: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
f350: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
f360: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
f370: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
f380: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
f390: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
f3a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f3b0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
f3c0: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
f3d0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
f3e0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f3f0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
f400: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
f410: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
f420: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
f430: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f440: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
f450: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
f460: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
f470: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
f480: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
f490: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
f4a0: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
f4b0: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
f4c0: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
f4d0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
f4e0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
f4f0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
f500: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
f510: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
f520: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f530: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
f540: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
f550: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f560: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
f570: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
f580: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
f590: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
f5a0: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
f5b0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
f5c0: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
f5d0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f5e0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
f5f0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
f600: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
f610: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
f620: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
f630: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
f640: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
f650: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
f660: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f670: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
f680: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
f690: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
f6a0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
f6b0: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
f6c0: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
f6d0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
f6e0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
f6f0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
f700: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
f710: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f720: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
f730: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
f740: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
f750: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
f760: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
f770: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
f780: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f790: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
f7a0: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
f7b0: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
f7c0: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
f7d0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
f7e0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
f7f0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
f800: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
f810: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
f820: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
f830: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
f840: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
f850: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
f860: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
f870: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
f880: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
f890: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
f8a0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
f8b0: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
f8c0: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
f8d0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
f8e0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
f8f0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
f900: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
f910: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
f920: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f930: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
f940: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
f950: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
f960: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
f970: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
f980: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
f990: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
f9a0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
f9b0: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
f9c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f9d0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
f9e0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
f9f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fa00: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
fa10: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
fa20: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
fa30: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fa40: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
fa50: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
fa60: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
fa70: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
fa80: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
fa90: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
faa0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
fab0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
fac0: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
fad0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
fae0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
faf0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
fb00: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
fb10: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
fb20: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
fb30: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
fb40: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
fb50: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
fb60: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
fb70: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
fb80: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
fb90: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
fba0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
fbb0: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
fbc0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
fbd0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
fbe0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
fbf0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
fc00: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
fc10: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
fc20: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
fc30: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
fc40: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
fc50: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
fc60: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
fc70: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
fc80: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
fc90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fca0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fcb0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
fcc0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
fcd0: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
fce0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
fcf0: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
fd00: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
fd10: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
fd20: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
fd30: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
fd40: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
fd50: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
fd60: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
fd70: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
fd80: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
fd90: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
fda0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
fdb0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
fdc0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
fdd0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
fde0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
fdf0: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
fe00: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
fe10: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
fe20: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
fe30: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
fe40: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
fe50: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
fe60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
fe70: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
fe80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
fe90: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fea0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
feb0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
fec0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
fed0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
fee0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
fef0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
ff00: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
ff10: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
ff20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ff30: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
ff40: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
ff50: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
ff60: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
ff70: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
ff80: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
ff90: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
ffa0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ffb0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
ffc0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
ffd0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
ffe0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
fff0: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
10000 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
10010 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
10020 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
10030 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10040 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
10050 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
10060 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
10070 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
10080 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
10090 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
100a0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
100b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
100c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
100d0 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
100e0 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
100f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10100 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
10110 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
10120 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
10130 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
10140 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
10150 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
10160 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
10170 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
10180 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10190 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
101a0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
101b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
101c0 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
101d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
101e0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
101f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10200 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
10210 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
10220 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
10230 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
10240 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
10250 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
10260 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
10270 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
10280 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10290 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
102a0 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
102b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
102c0 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
102d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
102e0 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
102f0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
10300 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
10310 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10320 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
10330 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
10340 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
10350 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10360 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
10370 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
10380 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10390 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
103a0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
103b0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
103c0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
103d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
103e0 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
103f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
10400 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
10410 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
10420 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
10430 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
10440 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
10450 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
10460 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10470 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
10480 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
10490 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
104a0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
104b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
104c0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
104d0 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
104e0 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
104f0 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10500 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
10510 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
10520 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
10530 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
10540 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
10550 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
10560 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
10570 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
10580 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
10590 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
105a0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
105b0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
105c0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
105d0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
105e0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
105f0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10600 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
10610 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
10620 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
10630 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
10640 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
10650 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
10660 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
10670 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
10680 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
10690 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
106a0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
106b0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
106c0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
106d0 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
106e0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
106f0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
10700 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
10710 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10720 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
10730 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
10740 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
10750 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
10760 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10770 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
10780 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
10790 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
107a0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
107b0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
107c0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
107d0 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
107e0 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
107f0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
10800 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
10810 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
10820 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
10830 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
10840 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
10850 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
10860 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
10870 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
10880 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
10890 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
108a0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
108b0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
108c0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
108d0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
108e0 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
108f0 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
10900 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
10910 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
10920 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
10930 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
10940 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10950 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
10960 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
10970 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
10980 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
10990 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
109a0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
109b0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
109c0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
109d0 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
109e0 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
109f0 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
10a00 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
10a10 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
10a20 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
10a30 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
10a40 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
10a50 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
10a60 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
10a70 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
10a80 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
10a90 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
10aa0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
10ab0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
10ac0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
10ad0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
10ae0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
10af0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
10b00 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
10b10 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
10b20 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
10b30 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
10b40 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
10b50 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
10b60 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
10b70 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
10b80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
10b90 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
10ba0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
10bb0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
10bc0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10bd0 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
10be0 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
10bf0 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
10c00 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
10c10 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
10c20 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
10c30 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
10c40 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
10c50 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
10c60 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
10c70 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
10c80 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
10c90 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
10ca0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
10cb0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
10cc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
10cd0 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
10ce0 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
10cf0 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
10d00 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
10d10 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
10d20 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
10d30 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
10d40 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
10d50 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
10d60 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
10d70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10d80 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
10d90 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
10da0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
10db0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
10dc0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
10dd0 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
10de0 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
10df0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
10e00 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
10e10 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
10e20 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
10e30 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
10e40 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
10e50 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
10e60 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
10e70 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
10e80 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
10e90 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
10ea0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
10eb0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
10ec0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
10ed0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
10ee0 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
10ef0 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
10f00 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
10f10 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
10f20 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
10f30 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
10f40 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
10f50 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
10f60 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
10f70 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
10f80 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
10f90 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
10fa0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
10fb0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
10fc0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10fd0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
10fe0 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
10ff0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
11000 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
11010 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
11020 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
11030 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11040 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
11050 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
11060 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
11070 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
11080 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
11090 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
110a0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
110b0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
110c0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
110d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
110e0 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
110f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11100 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
11110 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
11120 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
11130 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
11140 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
11150 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
11160 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
11170 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
11180 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
11190 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
111a0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
111b0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
111c0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
111d0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
111e0 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
111f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
11200 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
11210 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
11220 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
11230 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
11240 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
11250 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
11260 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
11270 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11280 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11290 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
112a0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
112b0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
112c0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
112d0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
112e0 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
112f0 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
11300 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11310 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
11320 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
11330 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
11340 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
11350 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
11360 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
11370 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
11380 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
11390 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
113a0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
113b0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
113c0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
113d0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
113e0 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
113f0 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
11400 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
11410 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
11420 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
11430 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11440 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11450 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
11460 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
11470 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
11480 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11490 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
114a0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
114b0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
114c0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
114d0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
114e0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
114f0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
11500 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
11510 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
11520 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
11530 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
11540 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
11550 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
11560 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11570 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
11580 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
11590 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
115a0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
115b0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
115c0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
115d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
115e0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
115f0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
11600 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
11610 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
11620 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11630 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
11640 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
11650 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
11660 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
11670 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
11680 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11690 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
116a0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
116b0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
116c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
116d0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
116e0 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
116f0 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
11700 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
11710 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
11720 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11730 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
11740 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
11750 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11760 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
11770 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11780 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
11790 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
117a0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
117b0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
117c0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
117d0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
117e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
117f0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
11800 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11810 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
11820 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
11830 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
11840 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
11850 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
11860 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
11870 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
11880 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11890 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
118a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
118b0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
118c0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
118d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
118e0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
118f0 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
11900 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
11910 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
11920 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
11930 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
11940 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
11950 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11960 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
11970 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11980 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
11990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
119a0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
119b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
119c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
119d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
119e0 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
119f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11a00 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
11a10 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11a20 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11a30 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11a40 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11a50 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11a60 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
11a70 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
11a80 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
11a90 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
11aa0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
11ab0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
11ac0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11ad0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
11ae0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
11af0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
11b00 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
11b10 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
11b20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
11b30 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11b40 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
11b50 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
11b60 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
11b70 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
11b80 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
11b90 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
11ba0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
11bb0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
11bc0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
11bd0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
11be0 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
11bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11c00 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
11c10 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
11c20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11c30 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11c40 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11c50 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11c60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11c70 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
11c80 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
11c90 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
11ca0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
11cb0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
11cc0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11cd0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
11ce0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
11cf0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
11d00 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
11d10 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
11d20 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11d30 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
11d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
11d50 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
11d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11d70 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
11d80 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
11d90 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11da0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
11db0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11dc0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11dd0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
11de0 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
11df0 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
11e00 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
11e10 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
11e20 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
11e30 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
11e40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11e50 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
11e60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
11e70 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
11e80 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
11e90 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
11ea0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11eb0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
11ec0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
11ed0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
11ee0 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
11ef0 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
11f00 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
11f10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11f20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11f30 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
11f40 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
11f50 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
11f60 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
11f70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11f80 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
11f90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
11fa0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
11fb0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
11fc0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
11fd0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11fe0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11ff0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12000 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12010 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12020 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12030 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
12040 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
12050 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
12060 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
12070 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12080 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12090 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
120a0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
120b0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
120c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
120d0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
120e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
120f0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12100 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12110 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12120 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
12130 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12140 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12150 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12160 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12170 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
12180 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12190 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
121a0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
121b0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
121c0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
121d0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
121e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
121f0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12200 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
12210 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12220 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12230 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12240 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12250 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12260 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12270 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12280 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12290 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
122a0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
122b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
122c0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
122d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
122e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
122f0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
12300 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12310 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
12320 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
12330 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12340 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12350 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
12360 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
12370 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12380 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12390 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
123a0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
123b0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
123c0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
123d0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
123e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
123f0 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
12400 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
12410 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
12420 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
12430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12440 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
12450 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
12460 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
12470 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12480 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
12490 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
124a0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
124b0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
124c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
124d0 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
124e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
124f0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
12500 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
12510 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
12520 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
12530 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
12540 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
12550 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
12560 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
12570 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
12580 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
12590 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
125a0 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
125b0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
125c0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
125d0 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
125e0 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
125f0 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
12600 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
12610 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
12620 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12630 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
12640 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12650 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12660 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12670 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
12680 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
12690 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
126a0 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
126b0 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
126c0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
126d0 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
126e0 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
126f0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
12700 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
12710 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
12720 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
12730 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
12740 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12750 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
12760 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
12770 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
12780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12790 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
127a0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
127b0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
127c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
127d0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
127e0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
127f0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
12800 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
12810 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
12820 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12830 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
12840 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
12850 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
12860 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
12870 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12880 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
12890 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
128a0 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
128b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
128c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
128d0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
128e0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
128f0 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
12900 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
12910 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
12920 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73   16..** The firs
12930 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
12940 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
12950 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
12960 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
12970 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12980 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12990 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
129a0 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74  e no more than t
129b0 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  wo scratch buffe
129c0 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20  rs per thread.  
129d0 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  So.** N should b
129e0 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74  e set to twice t
129f0 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
12a00 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
12a10 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  reads..** ^SQLit
12a20 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
12a30 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
12a40 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
12a50 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
12a60 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
12a70 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
12a80 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
12a90 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
12aa0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
12ab0 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
12ac0 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
12ad0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12ae0 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
12af0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
12b00 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
12b10 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
12b20 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
12b30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12b40 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
12b50 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12b60 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
12b70 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12b80 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
12b90 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
12ba0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
12bb0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
12bc0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
12bd0 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
12be0 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
12bf0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
12c00 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
12c10 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
12c20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
12c30 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
12c40 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
12c50 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
12c60 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
12c70 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
12c80 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12c90 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  E2 option..** Th
12ca0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
12cb0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12cc0 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
12cd0 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
12ce0 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
12cf0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
12d00 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
12d10 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
12d20 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
12d30 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
12d40 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
12d50 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
12d60 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
12d70 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
12d80 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
12d90 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
12da0 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
12db0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
12dc0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
12dd0 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
12de0 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
12df0 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
12e00 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
12e10 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
12e20 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
12e30 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
12e40 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
12e50 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
12e60 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
12e70 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
12e80 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
12e90 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
12ea0 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
12eb0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
12ec0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12ed0 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
12ee0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
12ef0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12f00 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
12f10 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
12f20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
12f30 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
12f40 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
12f50 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
12f60 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
12f70 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
12f80 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12f90 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
12fa0 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
12fb0 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
12fc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
12fd0 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
12fe0 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
12ff0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
13000 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13010 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
13020 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
13030 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
13040 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
13050 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
13060 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
13070 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
13080 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
13090 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
130a0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
130b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
130c0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
130d0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
130e0 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
130f0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
13100 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
13110 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
13120 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
13130 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
13140 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
13150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13160 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
13170 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13180 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
13190 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
131a0 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
131b0 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
131c0 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
131d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
131e0 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
131f0 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
13200 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13210 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
13220 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
13230 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
13240 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
13250 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
13260 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
13270 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
13280 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
13290 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
132a0 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
132b0 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
132c0 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
132d0 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
132e0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
132f0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
13300 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
13310 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
13320 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
13330 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
13340 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
13350 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
13360 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
13370 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
13380 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
13390 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
133a0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
133b0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
133c0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
133d0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
133e0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
133f0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
13400 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
13410 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
13420 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
13430 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
13440 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
13450 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
13460 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13470 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
13480 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
13490 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
134a0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
134b0 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
134c0 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
134d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
134e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
134f0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
13500 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
13510 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13520 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13530 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13540 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13550 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13560 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13570 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
13580 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13590 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
135a0 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
135b0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
135c0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
135d0 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
135e0 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
135f0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
13600 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
13610 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
13620 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
13630 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13640 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13650 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
13660 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
13670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13680 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
13690 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
136a0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
136b0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
136c0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
136d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
136e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
136f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
13700 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
13710 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
13720 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
13730 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
13740 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13750 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
13760 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13770 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
13780 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
13790 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
137a0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
137b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
137c0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
137d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
137e0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
137f0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13800 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13810 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13820 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13830 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13840 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13850 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
13860 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13870 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
13880 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
13890 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
138a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
138b0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
138c0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
138d0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
138e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
138f0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
13900 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
13910 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
13920 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
13930 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
13940 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
13950 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
13960 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
13970 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
13980 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
13990 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
139a0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
139b0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
139c0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
139d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
139e0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
139f0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
13a00 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
13a10 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
13a20 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
13a30 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
13a40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
13a50 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13a60 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
13a70 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13a80 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13a90 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
13aa0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13ab0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13ac0 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
13ad0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
13ae0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
13af0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13b00 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
13b10 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
13b20 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
13b30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13b40 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  on for the looka
13b50 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
13b60 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a  cator on each.**
13b70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13b80 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72  ction].  The fir
13b90 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
13ba0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
13bb0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
13bc0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
13bd0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
13be0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
13bf0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
13c00 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
13c10 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68  nection.)^  ^(Th
13c20 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
13c30 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74  he.** <i>default
13c40 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
13c50 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
13c60 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13c70 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20  IDE].** verb to 
13c80 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13c90 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
13ca0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
13cb0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
13cc0 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
13cd0 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
13ce0 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
13cf0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13d00 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
13d10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13d20 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
13d30 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13d40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13d50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13d60 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13d70 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
13d80 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
13d90 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
13da0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
13db0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
13dc0 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
13dd0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
13de0 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
13df0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
13e00 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
13e10 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
13e20 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13e30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
13e40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13e50 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
13e60 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13e70 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13e80 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
13e90 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
13ea0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13eb0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13ec0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13ed0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
13ee0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
13ef0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
13f00 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
13f10 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
13f20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13f30 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
13f40 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
13f50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13f60 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
13f70 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
13f80 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
13f90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
13fa0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
13fb0 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
13fc0 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
13fd0 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
13fe0 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
13ff0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14000 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
14010 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
14020 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
14030 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
14040 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
14050 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
14060 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
14070 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
14080 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
14090 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
140a0 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
140b0 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
140c0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
140d0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
140e0 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
140f0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
14100 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
14110 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
14120 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
14130 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
14140 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
14150 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
14160 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14170 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
14180 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
14190 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
141a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
141b0 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
141c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
141d0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
141e0 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
141f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
14200 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
14210 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
14220 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
14230 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
14240 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
14250 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
14260 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
14270 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
14280 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
14290 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
142a0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
142b0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
142c0 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
142d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
142e0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
142f0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
14300 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
14310 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
14320 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
14330 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
14340 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
14350 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
14360 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
14370 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
14380 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
14390 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
143a0 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
143b0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
143c0 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
143d0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
143e0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
143f0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
14400 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
14410 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
14420 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14440 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14450 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
14460 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
14470 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14480 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
14490 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
144a0 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
144b0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
144c0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
144d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
144e0 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
144f0 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
14500 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
14510 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
14520 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
14530 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
14540 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
14550 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
14560 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
14570 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
14580 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
14590 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
145a0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
145b0 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
145c0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
145d0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
145e0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
145f0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
14600 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
14610 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
14620 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
14630 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14640 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
14650 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
14660 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
14670 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
14680 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
14690 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
146a0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
146b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
146c0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
146d0 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
146e0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
146f0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
14700 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
14710 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
14720 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
14730 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
14740 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
14750 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
14760 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
14770 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14780 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
14790 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
147a0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
147b0 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
147c0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
147d0 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
147e0 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  r argument which
147f0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
14800 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20  as.** a boolean 
14810 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
14820 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
14830 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
14840 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a  g indices for.**
14850 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
14860 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
14870 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20  ptimizer.  ^The 
14880 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
14890 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
148a0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
148b0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
148c0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
148d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
148e0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
148f0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
14900 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
14910 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
14920 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
14930 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
14940 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
14950 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
14960 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
14970 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
14980 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
14990 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
149a0 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
149b0 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
149c0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
149d0 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
149e0 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
149f0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
14a00 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
14a10 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
14a20 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
14a30 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
14a40 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
14a50 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
14a60 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
14a70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14a80 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
14a90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14aa0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
14ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14ac0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
14ad0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14ae0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
14af0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
14b00 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
14b10 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
14b20 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
14b30 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
14b40 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
14b50 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
14b60 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
14b70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14b90 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
14ba0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14bb0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
14bc0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14bd0 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
14be0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14bf0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
14c00 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
14c10 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
14c20 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
14c30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
14c40 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
14c50 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
14c60 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
14c70 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
14c80 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
14c90 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
14ca0 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
14cb0 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
14cc0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
14cd0 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
14ce0 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
14cf0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
14d00 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
14d10 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
14d20 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
14d30 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14d40 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
14d50 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14d60 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
14d70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
14d80 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
14d90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14da0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
14db0 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
14dc0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
14dd0 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
14de0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
14df0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
14e00 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
14e10 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
14e20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
14e30 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
14e40 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
14e50 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
14e60 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
14e70 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
14e80 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
14e90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
14ea0 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
14eb0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
14ec0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
14ed0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14ee0 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
14ef0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
14f00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
14f10 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
14f20 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
14f30 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
14f40 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
14f50 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
14f60 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
14f70 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
14f80 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
14f90 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
14fa0 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
14fb0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14fc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
14fd0 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
14fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
14ff0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
15000 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15010 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
15020 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
15030 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
15040 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
15050 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
15060 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
15070 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
15080 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
15090 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
150a0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
150b0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
150c0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
150d0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
150e0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
150f0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
15100 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
15110 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
15120 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
15130 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
15140 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
15150 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
15160 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
15170 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
15180 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15190 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e  map size.** cann
151a0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 61 74  ot be changed at
151b0 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20   run-time.  Nor 
151c0 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  may the maximum 
151d0 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
151e0 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20  e.** exceed the 
151f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
15200 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
15210 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
15220 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
15230 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
15240 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
15250 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
15260 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
15270 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
15280 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
15290 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
152a0 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
152b0 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
152c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
152d0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
152e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
152f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15300 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
15310 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
15320 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
15330 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
15340 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 0a 2a  ed for Windows.*
15350 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
15360 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
15370 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
15380 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  acro defined..**
15390 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
153a0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
153b0 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
153c0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
153d0 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
153e0 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
153f0 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
15400 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20 3c  eated heap..** <
15410 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dl>.**.** [[SQL
15420 49 54 45 5f 43 4f 4e 46 49 47 5f 57 4f 52 4b 45  ITE_CONFIG_WORKE
15430 52 5f 54 48 52 45 41 44 53 5d 5d 0a 2a 2a 20 3c  R_THREADS]].** <
15440 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15450 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 0a  _WORKER_THREADS.
15460 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
15470 4f 4e 46 49 47 5f 57 4f 52 4b 45 52 5f 54 48 52  ONFIG_WORKER_THR
15480 45 41 44 53 20 74 61 6b 65 73 20 61 20 73 69 6e  EADS takes a sin
15490 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
154a0 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 74 20  type int..** It 
154b0 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 74  is used to set t
154c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 61 63  he number of bac
154d0 6b 67 72 6f 75 6e 64 20 77 6f 72 6b 65 72 20 74  kground worker t
154e0 68 72 65 61 64 73 20 74 68 61 74 20 6d 61 79 20  hreads that may 
154f0 62 65 0a 2a 2a 20 6c 61 75 6e 63 68 65 64 20 77  be.** launched w
15500 68 65 6e 20 73 6f 72 74 69 6e 67 20 6c 61 72 67  hen sorting larg
15510 65 20 61 6d 6f 75 6e 74 73 20 6f 66 20 64 61 74  e amounts of dat
15520 61 2e 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20  a. A value of 0 
15530 6d 65 61 6e 73 20 6c 61 75 6e 63 68 20 0a 2a 2a  means launch .**
15540 20 6e 6f 20 62 61 63 6b 67 72 6f 75 6e 64 20 74   no background t
15550 68 72 65 61 64 73 20 61 74 20 61 6c 6c 2e 20 54  hreads at all. T
15560 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
15570 72 20 6f 66 20 62 61 63 6b 67 72 6f 75 6e 64 20  r of background 
15580 74 68 72 65 61 64 73 20 0a 2a 2a 20 61 6c 6c 6f  threads .** allo
15590 77 65 64 20 69 73 20 63 6f 6e 66 69 67 75 72 65  wed is configure
155a0 64 20 61 74 20 62 75 69 6c 64 2d 74 69 6d 65 20  d at build-time 
155b0 62 79 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 41  by the SQLITE_MA
155c0 58 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  X_WORKER_THREADS
155d0 20 0a 2a 2a 20 70 72 65 2d 70 72 6f 63 65 73 73   .** pre-process
155e0 6f 72 20 6f 70 74 69 6f 6e 2e 20 0a 2a 2a 20 3c  or option. .** <
155f0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
15600 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
15610 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
15620 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15630 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15640 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
15650 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15660 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15670 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
15680 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15690 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
156a0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
156b0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
156c0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
156d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
156e0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
156f0 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
15700 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
15710 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15720 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
15730 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
15740 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
15750 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15760 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15770 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
15780 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
15790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
157a0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
157b0 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
157c0 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
157d0 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
157e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
157f0 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
15800 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
15810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15820 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
15830 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
15840 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
15850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15860 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15870 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
15880 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15890 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
158a0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
158b0 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
158c0 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
158d0 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
158e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
158f0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
15900 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
15910 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15920 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
15930 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
15940 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15950 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15960 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
15970 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
15980 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
15990 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
159a0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
159b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
159c0 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
159d0 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
159e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
159f0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
15a00 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
15a10 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15a20 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
15a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15a40 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
15a50 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15a60 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
15a70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15a80 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
15a90 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
15aa0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15ab0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15ac0 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
15ad0 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
15ae0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15af0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
15b00 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
15b10 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
15b20 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
15b30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15b40 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
15b50 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
15b60 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
15b70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 4f  SQLITE_CONFIG_WO
15b80 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20  RKER_THREADS    
15b90 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 6e 57 6f    24  /* int nWo
15ba0 72 6b 65 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rker */../*.** C
15bb0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
15bc0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
15bd0 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
15be0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
15bf0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
15c00 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
15c10 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
15c20 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
15c30 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
15c40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15c50 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
15c60 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15c70 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
15c80 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
15c90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
15ca0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
15cb0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
15cc0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
15cd0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
15ce0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
15cf0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
15d00 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
15d10 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
15d20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
15d30 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
15d40 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
15d50 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
15d60 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
15d70 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
15d80 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15d90 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
15da0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
15db0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
15dc0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
15dd0 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
15de0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15df0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
15e00 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
15e10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
15e20 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
15e30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
15e40 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
15e50 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
15e60 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
15e70 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
15e80 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
15e90 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
15ea0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
15eb0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
15ec0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
15ed0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15ee0 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
15ef0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
15f00 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15f10 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15f20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
15f30 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
15f40 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
15f50 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
15f60 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
15f70 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
15f80 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
15f90 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
15fa0 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
15fb0 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
15fc0 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
15fd0 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
15fe0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
15ff0 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
16000 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
16010 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
16020 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
16030 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
16040 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
16050 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
16060 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
16070 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
16080 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
16090 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
160a0 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
160b0 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
160c0 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
160d0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
160e0 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
160f0 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
16100 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
16110 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
16120 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
16130 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
16140 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
16150 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
16160 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
16170 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
16180 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
16190 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
161a0 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
161b0 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
161c0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
161d0 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
161e0 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
161f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
16200 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
16210 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
16220 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
16230 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
16240 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
16250 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
16260 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
16270 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
16280 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
16290 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
162a0 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
162b0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
162c0 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
162d0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
162e0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
162f0 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
16300 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
16310 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
16320 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
16330 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
16340 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
16350 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
16360 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
16370 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
16380 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
16390 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
163a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
163b0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
163c0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
163d0 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
163e0 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
163f0 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
16400 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
16410 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
16420 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
16430 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16440 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
16450 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
16460 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
16470 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
16480 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
16490 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
164a0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
164b0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
164c0 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
164d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
164e0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
164f0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
16500 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
16510 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
16520 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
16530 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
16540 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
16550 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
16560 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
16570 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
16580 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
16590 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
165a0 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
165b0 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
165c0 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
165d0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
165e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
165f0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
16600 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
16610 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
16620 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
16630 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
16640 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
16650 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
16660 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
16670 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
16680 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
16690 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
166a0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
166b0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
166c0 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
166d0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
166e0 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
166f0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
16700 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
16710 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
16720 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
16730 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16740 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
16750 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
16760 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
16770 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
16780 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
16790 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
167a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
167b0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
167c0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
167d0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
167e0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
167f0 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
16800 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
16810 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
16820 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
16830 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16840 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
16850 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
16860 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
16870 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
16880 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16890 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
168a0 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
168b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
168c0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
168d0 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
168e0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
168f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16900 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
16910 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
16920 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
16930 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
16940 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
16950 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
16960 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
16970 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
16980 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
16990 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
169a0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
169b0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
169c0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
169d0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
169e0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
169f0 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
16a00 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
16a10 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
16a20 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
16a30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16a40 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
16a50 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
16a60 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
16a70 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
16a80 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
16a90 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
16aa0 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
16ab0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
16ac0 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
16ad0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
16ae0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
16af0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
16b00 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
16b10 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
16b20 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
16b30 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
16b40 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
16b50 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
16b60 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
16b70 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
16b80 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
16b90 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
16ba0 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
16bb0 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
16bc0 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
16bd0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
16be0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
16bf0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
16c00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
16c10 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
16c20 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
16c30 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
16c40 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d  id] of the .** m
16c50 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
16c60 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
16c70 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c  nto a rowid tabl
16c80 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61  e or [virtual ta
16c90 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62  ble].** on datab
16ca0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
16cb0 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e  ..** ^Inserts in
16cc0 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  to [WITHOUT ROWI
16cd0 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  D] tables are no
16ce0 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e  t recorded..** ^
16cf0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
16d00 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20   [INSERT]s into 
16d10 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20  rowid tables.** 
16d20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
16d30 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ed on the databa
16d40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  se connection D,
16d50 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65   .** then sqlite
16d60 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16d70 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a  wid(D) returns z
16d80 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ero..**.** ^(If 
16d90 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
16da0 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
16db0 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
16dc0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
16dd0 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
16de0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
16df0 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
16e00 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
16e10 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
16e20 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
16e30 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
16e40 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
16e50 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
16e60 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
16e70 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
16e80 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
16e90 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
16ea0 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
16eb0 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
16ec0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
16ed0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
16ee0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
16ef0 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
16f00 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
16f10 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
16f20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
16f30 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
16f40 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
16f50 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
16f60 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
16f70 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
16f80 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
16f90 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
16fa0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
16fb0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
16fc0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
16fd0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
16fe0 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
16ff0 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
17000 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
17010 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
17020 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
17030 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
17040 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
17050 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
17060 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
17070 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
17080 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
17090 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
170a0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
170b0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
170c0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
170d0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
170e0 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
170f0 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
17100 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
17110 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
17120 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
17130 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
17140 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
17150 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
17160 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
17170 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
17180 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
17190 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
171a0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
171b0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
171c0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
171d0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
171e0 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
171f0 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
17200 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
17210 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
17220 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
17230 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
17240 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
17250 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
17260 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
17270 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
17280 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
17290 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
172a0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
172b0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
172c0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
172d0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
172e0 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
172f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
17300 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
17310 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
17320 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
17330 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
17340 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
17350 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
17360 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
17370 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
17380 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
17390 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
173a0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
173b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
173c0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
173d0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
173e0 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
173f0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
17400 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
17410 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
17420 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
17430 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
17440 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
17450 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
17460 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
17470 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
17480 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17490 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
174a0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
174b0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
174c0 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
174d0 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
174e0 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
174f0 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
17500 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
17510 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
17520 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
17530 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
17540 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
17550 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
17560 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
17570 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
17580 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17590 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
175a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
175b0 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
175c0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
175d0 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
175e0 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
175f0 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
17600 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
17610 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
17620 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
17630 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
17640 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
17650 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
17660 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
17670 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
17680 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17690 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
176a0 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
176b0 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
176c0 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
176d0 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
176e0 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
176f0 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
17700 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
17710 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
17720 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
17730 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
17740 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
17750 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
17760 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
17770 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
17780 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
17790 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
177a0 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
177b0 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
177c0 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
177d0 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
177e0 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
177f0 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
17800 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
17810 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
17820 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
17830 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
17840 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
17850 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
17860 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
17870 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
17880 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
17890 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
178a0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
178b0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
178c0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
178d0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
178e0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
178f0 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
17900 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
17910 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
17920 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
17930 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
17940 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
17950 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
17960 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
17970 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
17980 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
17990 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
179a0 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
179b0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
179c0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
179d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
179e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
179f0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
17a00 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
17a10 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
17a20 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
17a30 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
17a40 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
17a50 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
17a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
17a70 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
17a80 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
17a90 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17aa0 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
17ab0 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
17ac0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
17ad0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
17ae0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
17af0 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
17b00 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
17b10 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
17b20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
17b30 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
17b40 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
17b50 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
17b60 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
17b70 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
17b80 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
17b90 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
17ba0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
17bb0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
17bc0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
17bd0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
17be0 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
17bf0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
17c00 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
17c10 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17c20 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
17c30 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
17c40 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
17c50 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
17c60 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
17c70 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
17c80 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17c90 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
17ca0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17cb0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
17cc0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
17cd0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
17ce0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
17cf0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
17d00 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
17d10 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
17d20 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
17d30 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
17d40 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17d50 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17d60 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
17d70 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17d80 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17d90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17da0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
17db0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17dc0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
17dd0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17de0 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
17df0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
17e00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
17e10 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
17e20 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
17e30 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
17e40 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
17e50 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
17e60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17e70 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
17e80 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
17e90 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
17ea0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
17eb0 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
17ec0 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
17ed0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
17ee0 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
17ef0 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
17f00 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
17f10 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
17f20 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
17f30 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
17f40 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
17f50 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
17f60 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
17f70 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
17f80 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
17f90 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
17fa0 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
17fb0 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
17fc0 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
17fd0 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
17fe0 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
17ff0 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
18000 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
18010 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
18020 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
18030 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
18040 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
18050 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
18060 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
18070 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
18080 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
18090 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
180a0 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
180b0 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
180c0 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
180d0 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
180e0 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
180f0 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
18100 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
18110 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
18120 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
18130 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
18140 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
18150 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
18160 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
18170 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
18180 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
18190 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
181a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
181b0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
181c0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
181d0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
181e0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
181f0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
18200 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
18210 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
18220 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
18230 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
18240 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
18250 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
18260 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
18270 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18280 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
18290 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
182a0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
182b0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
182c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
182d0 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
182e0 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
182f0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
18300 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
18310 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
18320 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
18330 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
18340 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
18350 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
18360 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
18370 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
18380 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
18390 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
183a0 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
183b0 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
183c0 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
183d0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
183e0 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
183f0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
18400 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
18410 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
18420 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
18430 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
18440 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
18450 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
18460 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
18470 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18480 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
18490 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
184a0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
184b0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
184c0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
184d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
184e0 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
184f0 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
18500 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
18510 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
18520 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
18530 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
18540 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
18550 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
18560 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
18570 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
18580 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
18590 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
185a0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
185b0 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
185c0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
185d0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
185e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
185f0 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
18600 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
18610 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
18620 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
18630 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
18640 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
18650 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
18660 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
18670 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
18680 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
18690 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
186a0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
186b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
186c0 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
186d0 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
186e0 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
186f0 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
18700 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
18710 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
18720 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
18730 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
18740 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
18750 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
18760 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
18770 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
18780 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
18790 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
187a0 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
187b0 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
187c0 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
187d0 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
187e0 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
187f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18800 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
18810 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
18820 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
18830 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
18840 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
18850 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
18860 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
18870 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
18880 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18890 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
188a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
188b0 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
188c0 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
188d0 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
188e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
188f0 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
18900 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
18910 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
18920 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
18930 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
18940 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
18950 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
18960 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
18970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
18980 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
18990 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
189a0 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
189b0 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
189c0 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
189d0 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
189e0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
189f0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18a00 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
18a10 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
18a20 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
18a30 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
18a40 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
18a50 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
18a60 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
18a70 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
18a80 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
18a90 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
18aa0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
18ab0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
18ac0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
18ad0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
18ae0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
18af0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
18b00 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
18b10 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
18b20 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
18b30 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
18b40 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
18b50 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
18b60 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
18b70 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
18b80 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
18b90 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
18ba0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
18bb0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
18bc0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
18bd0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
18be0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
18bf0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
18c00 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
18c10 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
18c20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
18c30 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
18c40 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
18c50 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
18c60 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
18c70 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
18c80 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
18c90 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
18ca0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
18cb0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
18cc0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
18cd0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
18ce0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
18cf0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
18d00 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
18d10 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
18d20 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
18d30 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
18d40 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
18d50 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
18d60 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
18d70 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
18d80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
18d90 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
18da0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
18db0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
18dc0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
18dd0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
18de0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
18df0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
18e00 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
18e10 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
18e20 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
18e30 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
18e40 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
18e50 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
18e60 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
18e70 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
18e80 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18e90 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
18ea0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
18eb0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
18ec0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
18ed0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18ee0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
18ef0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
18f00 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
18f10 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
18f20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18f30 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
18f40 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
18f50 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
18f60 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
18f70 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
18f80 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
18f90 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
18fa0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
18fb0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
18fc0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
18fd0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
18fe0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
18ff0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
19000 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
19010 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
19020 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
19030 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
19040 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
19050 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
19060 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
19070 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19080 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
19090 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
190a0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
190b0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
190c0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
190d0 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rrors.**.** ^The
190e0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
190f0 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
19100 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
19110 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
19120 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
19130 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
19140 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
19150 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
19160 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
19170 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
19180 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
19190 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
191a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
191b0 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
191c0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
191d0 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
191e0 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
191f0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19200 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
19210 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
19220 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
19230 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
19240 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
19250 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
19260 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
19270 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
19280 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
19290 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
192a0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
192b0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
192c0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
192d0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
192e0 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
192f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
19300 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
19310 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
19320 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
19330 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
19340 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
19350 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
19360 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
19370 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
19380 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
19390 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
193a0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
193b0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
193c0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
193d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
193e0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
193f0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
19400 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
19410 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
19420 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
19430 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
19440 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
19450 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
19460 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
19470 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
19480 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
19490 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
194a0 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
194b0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
194c0 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
194d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
194e0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
194f0 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
19500 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
19510 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
19520 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
19530 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
19540 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
19550 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
19560 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
19570 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
19580 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
19590 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
195a0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
195b0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
195c0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
195d0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
195e0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
195f0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
19600 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
19610 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
19620 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
19630 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
19640 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
19650 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
19660 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
19670 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
19680 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 74  IOERR_BLOCKED] t
19690 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
196a0 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
196b0 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
196c0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
196d0 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
196e0 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
196f0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
19700 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
19710 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
19720 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
19730 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
19740 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
19750 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
19760 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
19770 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
19780 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
19790 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
197a0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
197b0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
197c0 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
197d0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
197e0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
197f0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
19800 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
19810 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
19820 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
19830 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
19840 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
19850 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
19860 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
19870 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
19880 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
19890 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
198a0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
198b0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
198c0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
198d0 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
198e0 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
198f0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
19900 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
19910 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
19920 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
19930 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
19940 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
19950 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
19960 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
19970 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
19980 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
19990 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
199a0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
199b0 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
199c0 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
199d0 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
199e0 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
199f0 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
19a00 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
19a10 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
19a20 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
19a30 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
19a40 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
19a50 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
19a60 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
19a70 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
19a80 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
19a90 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
19aa0 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
19ab0 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
19ac0 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
19ad0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
19ae0 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
19af0 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
19b00 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73  ders.  ^If it is
19b10 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
19b20 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
19b30 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
19b40 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
19b50 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
19b60 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
19b70 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
19b80 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
19b90 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
19ba0 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
19bb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
19bc0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
19bd0 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
19be0 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69  _BLOCKED].  ^Thi
19bf0 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
19c00 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
19c10 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
19c20 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
19c30 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
19c40 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
19c50 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
19c60 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
19c70 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
19c80 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
19c90 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
19ca0 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
19cb0 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
19cc0 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
19cd0 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  rtant..**.** ^(T
19ce0 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
19cf0 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
19d00 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
19d10 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
19d20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19d30 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
19d40 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
19d50 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
19d60 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
19d70 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
19d80 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
19d90 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
19da0 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74  )].** or evaluat
19db0 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79  ing [PRAGMA busy
19dc0 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c  _timeout=N] will
19dd0 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62   change the.** b
19de0 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20  usy handler and 
19df0 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70  thus clear any p
19e00 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75  reviously set bu
19e10 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
19e20 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
19e30 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
19e40 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
19e50 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
19e60 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
19e70 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
19e80 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
19e90 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72  ndler.  In other
19ea0 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62   words,.** the b
19eb0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e  usy handler is n
19ec0 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41  ot reentrant.  A
19ed0 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
19ee0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
19ef0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
19f00 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
19f10 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
19f20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
19f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
19f40 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
19f50 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
19f60 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
19f70 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
19f80 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19f90 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
19fa0 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
19fb0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
19fc0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
19fd0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a  Busy Timeout.**.
19fe0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
19ff0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1a000 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1a010 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1a020 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1a030 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1a040 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1a050 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1a060 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1a070 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1a080 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1a090 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1a0a0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1a0b0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1a0c0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1a0d0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1a0e0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1a0f0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1a100 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1a110 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1a120 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1a130 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1a140 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1a150 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
1a160 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
1a170 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
1a180 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1a190 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
1a1a0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
1a1b0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
1a1c0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
1a1d0 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
1a1e0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1a1f0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1a200 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
1a210 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1a220 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1a230 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
1a240 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
1a250 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
1a260 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
1a270 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
1a280 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
1a290 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1a2a0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
1a2b0 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
1a2c0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
1a2d0 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
1a2e0 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
1a2f0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
1a300 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1a310 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
1a320 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
1a330 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1a340 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
1a350 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
1a360 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
1a370 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1a380 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1a390 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1a3a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1a3b0 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1a3c0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1a3d0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1a3e0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1a3f0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1a400 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1a410 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1a420 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1a430 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1a440 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1a450 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1a460 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1a470 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1a480 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1a490 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1a4a0 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1a4b0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1a4c0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1a4d0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1a4e0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1a4f0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1a500 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1a510 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1a520 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1a530 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1a540 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1a550 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1a560 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1a570 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1a580 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1a590 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1a5a0 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1a5b0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1a5c0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1a5d0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1a5e0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1a5f0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1a600 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1a610 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1a620 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1a630 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1a640 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1a650 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1a660 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1a670 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1a680 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1a690 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1a6a0 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1a6b0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1a6c0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1a6d0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1a6e0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1a6f0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1a700 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1a710 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1a720 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1a730 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1a740 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1a750 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1a760 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1a770 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1a780 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1a790 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1a7a0 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1a7b0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1a7c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1a7d0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1a7e0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1a7f0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1a800 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1a810 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1a820 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1a830 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1a840 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1a850 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1a860 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1a870 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1a880 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1a890 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1a8a0 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1a8b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a8c0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1a8d0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1a8e0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1a8f0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1a900 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1a910 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1a920 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1a930 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1a940 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1a950 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1a960 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1a970 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1a980 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1a990 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1a9a0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1a9b0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1a9c0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1a9d0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1a9e0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1a9f0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1aa00 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1aa10 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1aa20 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1aa30 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1aa40 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1aa50 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1aa60 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1aa70 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1aa80 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1aa90 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1aaa0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1aab0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1aac0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1aad0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1aae0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1aaf0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1ab00 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1ab10 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1ab20 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1ab30 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1ab40 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1ab50 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1ab60 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1ab70 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1ab80 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1ab90 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1aba0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1abb0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1abc0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1abd0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1abe0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1abf0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1ac00 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1ac10 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1ac20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1ac30 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1ac40 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1ac50 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1ac60 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1ac70 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1ac80 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1ac90 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1aca0 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1acb0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1acc0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1acd0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1ace0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1acf0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1ad00 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1ad10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ad20 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1ad30 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1ad40 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1ad50 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1ad60 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1ad70 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1ad80 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1ad90 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1ada0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1adb0 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1adc0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1add0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1ade0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1adf0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1ae00 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1ae10 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1ae20 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1ae30 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1ae40 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1ae50 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1ae60 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1ae70 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1ae80 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1ae90 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1aea0 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1aeb0 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1aec0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1aed0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1aee0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1aef0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1af00 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1af10 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1af20 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1af30 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1af40 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1af50 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1af60 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1af70 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1af80 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1af90 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1afa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
1afb0 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1afc0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1afd0 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1afe0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1aff0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1b000 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1b010 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1b020 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1b030 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1b040 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1b050 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1b060 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1b070 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1b080 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1b090 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1b0a0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1b0b0 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1b0c0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1b0d0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1b0e0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1b0f0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1b100 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
1b110 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1b120 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
1b130 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b140 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
1b150 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
1b160 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1b170 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
1b180 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
1b190 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
1b1a0 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
1b1b0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
1b1c0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1b1d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b1e0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1b1f0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1b200 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1b210 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1b220 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1b230 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1b240 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b250 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1b260 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1b270 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1b280 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1b290 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1b2a0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1b2b0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1b2c0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1b2d0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1b2e0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1b2f0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1b300 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1b310 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1b320 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1b330 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1b340 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1b350 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1b360 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1b370 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1b380 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1b390 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1b3a0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1b3b0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1b3c0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1b3d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1b3e0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1b3f0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1b400 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1b410 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1b420 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1b430 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1b440 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1b450 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1b460 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1b470 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1b480 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1b490 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1b4a0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1b4b0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1b4c0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1b4d0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1b4e0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1b4f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1b500 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1b510 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1b520 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1b530 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1b540 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1b550 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1b560 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1b570 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1b580 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1b590 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1b5a0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1b5b0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1b5c0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1b5d0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1b5e0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1b5f0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1b600 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1b610 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1b620 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1b630 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1b640 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1b650 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1b660 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1b670 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1b680 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1b690 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1b6a0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1b6b0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1b6c0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1b6d0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1b6e0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1b6f0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1b700 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1b710 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1b720 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1b730 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1b740 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1b750 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1b760 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1b770 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1b780 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1b790 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1b7a0 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1b7b0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1b7c0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1b7d0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1b7e0 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1b7f0 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1b800 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1b810 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1b820 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1b830 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1b840 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1b850 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1b860 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1b870 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1b880 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
1b890 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1b8a0 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1b8b0 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1b8c0 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1b8d0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1b8e0 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1b8f0 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1b900 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1b910 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1b920 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1b930 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1b940 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1b950 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1b960 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1b970 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1b980 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1b990 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1b9a0 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1b9b0 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1b9c0 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1b9d0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1b9e0 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1b9f0 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1ba00 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1ba10 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1ba20 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1ba30 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1ba40 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1ba50 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1ba60 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1ba70 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1ba80 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1ba90 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1baa0 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1bab0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1bac0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1bad0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1bae0 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1baf0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1bb00 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1bb10 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1bb20 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1bb30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1bb40 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1bb50 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1bb60 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1bb70 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1bb80 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1bb90 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1bba0 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1bbb0 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1bbc0 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
1bbd0 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
1bbe0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1bbf0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1bc00 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1bc10 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
1bc20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
1bc30 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1bc40 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1bc50 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
1bc60 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
1bc70 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
1bc80 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
1bc90 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
1bca0 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
1bcb0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1bcc0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1bcd0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1bce0 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
1bcf0 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
1bd00 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1bd10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
1bd20 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
1bd30 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
1bd40 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
1bd50 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
1bd60 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
1bd70 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
1bd80 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
1bd90 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
1bda0 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
1bdb0 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
1bdc0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
1bdd0 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
1bde0 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
1bdf0 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
1be00 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
1be10 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
1be20 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
1be30 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
1be40 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
1be50 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
1be60 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
1be70 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
1be80 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
1be90 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
1bea0 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
1beb0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
1bec0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
1bed0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1bee0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1bef0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1bf00 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1bf10 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
1bf20 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1bf30 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1bf40 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1bf50 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1bf60 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1bf70 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1bf80 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
1bf90 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
1bfa0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
1bfb0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
1bfc0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
1bfd0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
1bfe0 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
1bff0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1c000 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1c010 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1c020 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1c030 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1c040 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1c050 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1c060 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1c070 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1c080 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1c090 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1c0a0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1c0b0 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
1c0c0 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1c0d0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1c0e0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1c0f0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1c100 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1c110 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1c120 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1c130 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1c140 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
1c150 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1c160 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1c170 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1c180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c190 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1c1a0 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1c1b0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1c1c0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1c1d0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1c1e0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1c1f0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1c200 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1c210 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1c220 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1c230 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1c240 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1c250 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1c260 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1c270 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1c280 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1c290 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1c2a0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1c2b0 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1c2c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c2d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1c2e0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1c2f0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1c300 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1c310 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1c320 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1c330 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1c340 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1c350 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1c360 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1c370 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1c380 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1c390 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1c3a0 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1c3b0 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1c3c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c3d0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1c3e0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1c3f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1c400 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1c410 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  inter..**.** ^Ca
1c420 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1c430 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1c440 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1c450 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1c460 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1c470 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1c480 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1c490 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1c4a0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1c4b0 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1c4c0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1c4d0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1c4e0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1c4f0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1c500 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1c510 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1c520 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1c530 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1c540 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1c550 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1c560 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1c570 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1c580 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1c590 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1c5a0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1c5b0 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1c5c0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1c5d0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1c5e0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1c5f0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1c600 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1c610 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1c620 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1c630 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1c640 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1c650 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1c660 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1c670 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1c680 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1c690 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1c6a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1c6b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1c6c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
1c6d0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1c6e0 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1c6f0 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1c700 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61  location to be a
1c710 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c  t least N bytes,
1c720 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
1c730 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1c740 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  ter.  The memory
1c750 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
1c760 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65  e resized is the
1c770 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1c780 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20  ter.)^ ^ If the 
1c790 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1c7a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1c7b0 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  oc().** is a NUL
1c7c0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
1c7d0 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
1c7e0 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
1c7f0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
1c800 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e  alloc(N) where N
1c810 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   is the second p
1c820 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c830 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1c840 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64  * ^If the second
1c850 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c860 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1c870 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1c880 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1c890 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1c8a0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1c8b0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1c8c0 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65  e3_free(P) where
1c8d0 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20   P is the first 
1c8e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1c8f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1c900 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
1c910 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20  loc() returns a 
1c920 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1c930 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1c940 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1c950 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1c960 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69   NULL if suffici
1c970 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e  ent memory is un
1c980 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1c990 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1c9a0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1c9b0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1c9c0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1c9d0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1c9e0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1c9f0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1ca00 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1ca10 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1ca20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ca30 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1ca40 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1ca50 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1ca60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
1ca70 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  urns NULL, then 
1ca80 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1ca90 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66  tion.** is not f
1caa0 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  reed..**.** ^The
1cab0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
1cac0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1cad0 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  oc() and sqlite3
1cae0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
1caf0 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
1cb00 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
1cb10 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
1cb20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
1cb30 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
1cb40 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
1cb50 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
1cb60 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1cb70 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
1cb80 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
1cb90 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
1cba0 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
1cbb0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
1cbc0 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
1cbd0 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
1cbe0 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
1cbf0 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
1cc00 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
1cc10 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
1cc20 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
1cc30 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
1cc40 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
1cc50 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
1cc60 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
1cc70 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1cc80 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
1cc90 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
1cca0 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1ccb0 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
1ccc0 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
1ccd0 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
1cce0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1ccf0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1cd00 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1cd10 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1cd20 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1cd30 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1cd40 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1cd50 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1cd60 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1cd70 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1cd80 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1cd90 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1cda0 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1cdb0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1cdc0 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
1cdd0 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
1cde0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1cdf0 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1ce00 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1ce10 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1ce20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1ce30 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1ce40 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1ce50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1ce60 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1ce70 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1ce80 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1ce90 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1cea0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1ceb0 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1cec0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1ced0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1cee0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1cef0 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1cf00 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1cf10 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1cf20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1cf30 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1cf40 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1cf50 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1cf60 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1cf70 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1cf80 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1cf90 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1cfa0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1cfb0 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
1cfc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1cfd0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1cfe0 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
1cff0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
1d000 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
1d010 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d020 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
1d030 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
1d040 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
1d050 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
1d060 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
1d070 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
1d080 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
1d090 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d0a0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1d0b0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1d0c0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
1d0d0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
1d0e0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
1d0f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1d100 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
1d110 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1d120 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1d130 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1d140 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1d150 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
1d160 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
1d170 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
1d180 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
1d190 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
1d1a0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1d1b0 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
1d1c0 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
1d1d0 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
1d1e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1d1f0 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
1d200 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1d210 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
1d220 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
1d230 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1d240 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1d250 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1d260 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d270 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
1d280 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
1d290 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
1d2a0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
1d2b0 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
1d2c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
1d2d0 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
1d2e0 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
1d2f0 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
1d300 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
1d310 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
1d320 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d330 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
1d340 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
1d350 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
1d360 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
1d370 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
1d380 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d390 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
1d3a0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
1d3b0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
1d3c0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d3d0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
1d3e0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
1d3f0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
1d400 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1d410 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
1d420 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1d430 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
1d440 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
1d450 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1d460 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
1d470 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
1d480 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1d490 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
1d4a0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
1d4b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
1d4c0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
1d4d0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
1d4e0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
1d4f0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
1d500 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
1d510 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
1d520 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
1d530 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
1d540 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
1d550 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1d560 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
1d570 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
1d580 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
1d590 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
1d5a0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
1d5b0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
1d5c0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
1d5d0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
1d5e0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
1d5f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
1d600 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1d610 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
1d620 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
1d630 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
1d640 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
1d650 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
1d660 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1d670 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
1d680 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
1d690 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
1d6a0 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
1d6b0 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 50 20 63  an one, then P c
1d6c0 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  an be a NULL poi
1d6d0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  nter..**.** ^If 
1d6e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73  this routine has
1d6f0 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f   not been previo
1d700 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69  usly called or i
1d710 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a  f the previous.*
1d720 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73  * call had N les
1d730 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e  s than one, then
1d740 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
1d750 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1d760 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  ness.** obtained
1d770 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
1d780 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
1d790 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1d7a0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1d7b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65  ..** ^If the pre
1d7c0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
1d7d0 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61  is routine had a
1d7e0 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65  n N of 1 or more
1d7f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 70 73 65   then.** the pse
1d800 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1d810 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1d820 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1d830 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1d840 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1d850 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1d860 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
1d870 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1d880 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1d890 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1d8a0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1d8b0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1d8c0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
1d8d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1d8e0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1d8f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d900 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1d910 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1d920 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1d930 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1d940 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1d950 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1d960 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1d970 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1d980 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1d990 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1d9a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d9b0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1d9c0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1d9d0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1d9e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d9f0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1da00 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1da10 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1da20 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1da30 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1da40 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1da50 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1da60 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1da70 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1da80 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1da90 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1daa0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1dab0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1dac0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1dad0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1dae0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1daf0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1db00 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1db10 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1db20 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1db30 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1db40 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1db50 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1db60 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1db70 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1db80 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1db90 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1dba0 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1dbb0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1dbc0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1dbd0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1dbe0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1dbf0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1dc00 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1dc10 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1dc20 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1dc30 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1dc40 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1dc50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1dc60 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1dc70 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1dc80 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1dc90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1dca0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1dcb0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1dcc0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1dcd0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1dce0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1dcf0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1dd00 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1dd10 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1dd20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1dd30 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1dd40 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1dd50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1dd60 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1dd70 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1dd80 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1dd90 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1dda0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1ddb0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1ddc0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1ddd0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1dde0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1ddf0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1de00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1de10 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1de20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1de30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1de40 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1de50 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1de60 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1de70 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
1de80 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1de90 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
1dea0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1deb0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1dec0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
1ded0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
1dee0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
1def0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
1df00 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
1df10 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
1df20 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
1df30 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1df40 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1df50 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
1df60 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1df70 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1df80 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
1df90 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1dfa0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
1dfb0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
1dfc0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1dfd0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1dfe0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
1dff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e000 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
1e010 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
1e020 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
1e030 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1e040 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1e050 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1e060 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
1e070 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
1e080 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
1e090 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1e0a0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
1e0b0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1e0c0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
1e0d0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
1e0e0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
1e0f0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
1e100 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
1e110 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1e120 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
1e130 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1e140 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
1e150 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1e160 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
1e170 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
1e180 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
1e190 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
1e1a0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
1e1b0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
1e1c0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
1e1d0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
1e1e0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
1e1f0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
1e200 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
1e210 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
1e220 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
1e230 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
1e240 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
1e250 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1e260 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
1e270 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
1e280 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
1e290 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
1e2a0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
1e2b0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
1e2c0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
1e2d0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
1e2e0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
1e2f0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
1e300 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
1e310 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
1e320 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
1e330 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
1e340 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
1e350 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
1e360 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
1e370 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
1e380 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
1e390 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
1e3a0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
1e3b0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
1e3c0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
1e3d0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
1e3e0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
1e3f0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
1e400 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
1e410 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
1e420 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1e430 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
1e440 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
1e450 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
1e460 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
1e470 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
1e480 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
1e490 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
1e4a0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
1e4b0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
1e4c0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
1e4d0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
1e4e0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
1e4f0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
1e500 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
1e510 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
1e520 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
1e530 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
1e540 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
1e550 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
1e560 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
1e570 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
1e580 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
1e590 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
1e5a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1e5b0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
1e5c0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
1e5d0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e5e0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
1e5f0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
1e600 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
1e610 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
1e620 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
1e630 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
1e640 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
1e650 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1e660 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
1e670 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e680 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1e690 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1e6a0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1e6b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e6c0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1e6d0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
1e6e0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
1e6f0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1e700 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1e710 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1e720 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1e730 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1e740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1e750 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1e760 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1e770 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1e780 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
1e790 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1e7a0 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
1e7b0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
1e7c0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
1e7d0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
1e7e0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
1e7f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
1e800 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
1e810 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
1e820 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
1e830 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
1e840 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
1e850 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
1e860 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
1e870 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
1e880 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1e890 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
1e8a0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
1e8b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1e8c0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
1e8d0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
1e8e0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1e8f0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
1e900 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
1e910 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
1e920 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
1e930 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
1e940 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e950 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
1e960 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
1e970 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
1e980 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1e990 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
1e9a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1e9b0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
1e9c0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
1e9d0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
1e9e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
1e9f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1ea00 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1ea10 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1ea20 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1ea30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1ea40 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1ea50 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1ea60 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1ea70 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1ea80 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1ea90 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1eaa0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1eab0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1eac0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1ead0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
1eae0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
1eaf0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
1eb00 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
1eb10 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
1eb20 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
1eb30 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
1eb40 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
1eb50 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
1eb60 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1eb70 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1eb80 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
1eb90 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
1eba0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1ebb0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1ebc0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
1ebd0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
1ebe0 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54  used as a [SQLIT
1ebf0 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74  E_ROLLBACK | ret
1ec00 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f  urn code].** fro
1ec10 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1ec20 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
1ec30 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
1ec40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ec50 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
1ec60 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
1ec70 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
1ec80 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
1ec90 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
1eca0 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
1ecb0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
1ecc0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
1ecd0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
1ece0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1ecf0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
1ed00 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1ed10 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1ed20 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1ed30 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1ed40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1ed50 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1ed60 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1ed70 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1ed80 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1ed90 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1eda0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1edb0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1edc0 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1edd0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1ede0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1edf0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1ee00 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1ee10 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1ee20 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1ee30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1ee40 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1ee50 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1ee60 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1ee70 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1ee80 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1ee90 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1eea0 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1eeb0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1eec0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1eed0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1eee0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1eef0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1ef00 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1ef10 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1ef20 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1ef30 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1ef40 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
1ef50 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1ef60 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
1ef70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1ef80 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1ef90 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
1efa0 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
1efb0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
1efc0 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
1efd0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1efe0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1eff0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1f000 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1f010 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1f020 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1f030 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1f040 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1f050 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1f060 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1f070 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1f080 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1f090 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
1f0a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f0b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f0c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
1f0d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
1f0e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
1f0f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f100 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
1f110 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
1f120 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1f130 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f140 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f150 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1f160 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
1f170 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f180 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f190 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f1a0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
1f1b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1f1c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1f1d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f1e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1f1f0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
1f200 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f210 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f220 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f230 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1f240 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
1f250 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1f260 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f270 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f280 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1f290 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
1f2a0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1f2b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f2c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f2d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
1f2e0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
1f2f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1f300 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f310 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f320 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
1f330 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
1f340 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1f350 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f360 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f370 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
1f380 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
1f390 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f3a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f3b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f3c0 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
1f3d0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
1f3e0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1f3f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f400 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f410 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
1f420 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
1f430 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1f440 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f450 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f460 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
1f470 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
1f480 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1f490 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f4a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f4b0 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
1f4c0 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
1f4d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f4e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f4f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f500 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
1f510 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
1f520 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1f530 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f550 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
1f560 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
1f570 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1f580 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f590 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f5a0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1f5b0 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
1f5c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1f5d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f5e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f5f0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
1f600 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
1f610 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1f620 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f630 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
1f640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1f650 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1f660 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f670 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f680 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
1f690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
1f6a0 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
1f6b0 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
1f6c0 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
1f6d0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
1f6e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
1f6f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f700 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1f710 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f720 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
1f730 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
1f740 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1f750 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f760 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f770 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
1f780 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
1f790 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1f7a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f7b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f7c0 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
1f7d0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
1f7e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f7f0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1f800 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f810 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
1f820 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
1f830 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
1f840 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f850 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f860 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
1f870 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
1f880 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1f890 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f8a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f8b0 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
1f8c0 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
1f8d0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
1f8e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f8f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f900 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
1f910 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
1f920 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
1f930 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f940 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f950 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
1f960 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
1f970 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f980 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f990 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f9a0 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
1f9b0 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
1f9c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1f9d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1f9e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f9f0 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
1fa00 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
1fa10 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1fa20 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1fa30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
1fa40 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
1fa50 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
1fa60 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
1fa70 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
1fa80 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
1fa90 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
1faa0 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
1fab0 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
1fac0 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
1fad0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
1fae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1faf0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
1fb00 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
1fb10 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49  e SQLITE_RECURSI
1fb20 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33  VE            33
1fb30 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1fb40 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1fb50 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20        */../*.** 
1fb60 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1fb70 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1fb80 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1fb90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1fba0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1fbb0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1fbc0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1fbd0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1fbe0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1fbf0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1fc00 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1fc10 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1fc20 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1fc30 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1fc40 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1fc50 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1fc60 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1fc70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1fc80 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1fc90 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1fca0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1fcb0 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1fcc0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1fcd0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1fce0 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1fcf0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1fd00 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1fd10 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1fd20 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1fd30 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1fd40 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1fd50 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1fd60 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1fd70 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1fd80 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1fd90 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1fda0 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1fdb0 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1fdc0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1fdd0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1fde0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
1fdf0 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
1fe00 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
1fe10 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
1fe20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
1fe30 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
1fe40 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
1fe50 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
1fe60 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
1fe70 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
1fe80 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1fe90 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1fea0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1feb0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1fec0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1fed0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1fee0 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1fef0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1ff00 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1ff10 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1ff20 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1ff30 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1ff40 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1ff50 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1ff60 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1ff70 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
1ff80 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
1ff90 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
1ffa0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
1ffb0 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
1ffc0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
1ffd0 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
1ffe0 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
1fff0 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
20000 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
20010 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
20020 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
20030 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
20040 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
20050 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
20060 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
20070 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
20080 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
20090 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
200a0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
200b0 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
200c0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
200d0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
200e0 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
200f0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
20100 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
20110 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ite..*/.void *sq
20120 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
20130 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
20140 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
20150 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
20160 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
20170 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
20180 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
20190 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
201a0 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
201b0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
201c0 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
201d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
201e0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
201f0 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
20200 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
20210 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
20220 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
20230 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
20240 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
20250 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
20260 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
20270 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
20280 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
20290 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
202a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
202b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
202c0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
202d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
202e0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
202f0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
20300 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
20310 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
20320 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
20330 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
20340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
20350 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
20360 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
20370 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
20380 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
20390 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
203a0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
203b0 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d   is the approxim
203c0 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  ate number of .*
203d0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
203e0 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
203f0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
20400 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
20410 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
20420 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
20430 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20  lback X.  ^If N 
20440 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
20450 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
20460 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73  ss.** handler is
20470 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
20480 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
20490 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
204a0 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
204b0 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
204c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
204d0 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
204e0 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
204f0 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
20500 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
20510 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
20520 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
20530 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
20540 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
20550 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
20560 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
20570 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
20580 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
20590 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
205a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
205b0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
205c0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
205d0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
205e0 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
205f0 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
20600 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
20610 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
20620 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
20630 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
20640 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
20650 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
20660 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
20670 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
20680 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
20690 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
206a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
206b0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
206c0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
206d0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
206e0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
206f0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
20700 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
20710 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
20720 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
20730 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
20740 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
20750 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
20760 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
20770 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
20780 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
20790 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
207a0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
207b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
207c0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
207d0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
207e0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
207f0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
20800 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
20810 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
20820 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
20830 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
20840 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
20850 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
20860 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
20870 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
20880 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
20890 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
208a0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
208b0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
208c0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
208d0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
208e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
208f0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
20900 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
20910 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
20920 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
20930 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
20940 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
20950 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
20960 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
20970 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
20980 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
20990 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
209a0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
209b0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
209c0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
209d0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
209e0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
209f0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
20a00 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20a10 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
20a20 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
20a30 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
20a40 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
20a50 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
20a60 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
20a70 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
20a80 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
20a90 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
20aa0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
20ab0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
20ac0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
20ad0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
20ae0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
20af0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
20b00 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
20b10 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
20b20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
20b30 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
20b40 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
20b50 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
20b60 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
20b70 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
20b80 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
20b90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
20ba0 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
20bb0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
20bc0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
20bd0 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
20be0 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
20bf0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
20c00 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
20c10 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
20c20 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
20c30 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
20c40 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
20c50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
20c60 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
20c70 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
20c80 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
20c90 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
20ca0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
20cb0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
20cc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
20cd0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
20ce0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
20cf0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
20d00 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
20d10 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
20d20 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
20d30 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
20d40 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
20d50 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
20d60 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
20d70 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
20d80 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
20d90 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
20da0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
20db0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
20dc0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
20dd0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
20de0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
20df0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
20e00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
20e10 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
20e20 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
20e30 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
20e40 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
20e50 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
20e60 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
20e70 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
20e80 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
20e90 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
20ea0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20eb0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20ec0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
20ed0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
20ee0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
20ef0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
20f00 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
20f10 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
20f20 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
20f30 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
20f40 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
20f50 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
20f60 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
20f70 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
20f80 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
20f90 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
20fa0 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
20fb0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
20fc0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
20fd0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
20fe0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
20ff0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
21000 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
21010 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
21020 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
21030 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
21040 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
21050 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
21060 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
21070 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
21080 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21090 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
210a0 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
210b0 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
210c0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
210d0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
210e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
210f0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
21100 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
21110 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
21120 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
21130 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
21140 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
21150 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
21160 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
21170 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
21180 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
21190 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
211a0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
211b0 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
211c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
211d0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
211e0 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
211f0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
21200 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
21210 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
21220 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
21230 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
21240 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21250 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
21260 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
21270 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
21280 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
21290 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
212a0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
212b0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
212c0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
212d0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
212e0 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
212f0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
21300 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
21310 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21320 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
21330 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
21340 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
21350 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
21360 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
21370 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
21380 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
21390 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
213a0 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
213b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
213c0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
213d0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
213e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
213f0 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
21400 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
21410 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
21420 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
21430 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
21440 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
21450 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
21460 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
21470 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
21480 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
21490 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
214a0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
214b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
214c0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
214d0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
214e0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
214f0 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
21500 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
21510 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
21520 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21530 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
21540 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
21550 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
21560 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
21570 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
21580 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
21590 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
215a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
215b0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
215c0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
215d0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
215e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
215f0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
21600 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
21610 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
21620 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
21630 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
21640 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
21650 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
21660 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
21670 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
21680 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
21690 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
216a0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
216b0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
216c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
216d0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
216e0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
216f0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
21700 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
21710 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
21720 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
21730 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
21740 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
21750 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
21760 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
21770 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
21780 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
21790 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
217a0 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
217b0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
217c0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
217d0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
217e0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
217f0 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
21800 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
21810 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
21820 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
21830 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
21840 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
21850 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
21860 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
21870 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
21880 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
21890 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
218a0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
218b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
218c0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
218d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
218e0 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
218f0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
21900 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
21910 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
21920 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
21930 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
21940 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
21950 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
21960 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
21970 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
21980 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
21990 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
219a0 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
219b0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
219c0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
219d0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
219e0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
219f0 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
21a00 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
21a10 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21a20 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
21a30 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
21a40 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
21a50 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
21a60 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
21a70 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
21a80 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
21a90 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
21aa0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
21ab0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
21ac0 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
21ad0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
21ae0 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
21af0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
21b00 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
21b10 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
21b20 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
21b30 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
21b40 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
21b50 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
21b60 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
21b70 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
21b80 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
21b90 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
21ba0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
21bb0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
21bc0 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
21bd0 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
21be0 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
21bf0 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
21c00 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
21c10 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
21c20 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
21c30 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
21c40 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
21c50 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
21c60 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
21c70 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
21c80 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
21c90 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
21ca0 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
21cb0 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
21cc0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
21cd0 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
21ce0 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
21cf0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
21d00 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
21d10 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
21d20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
21d30 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
21d40 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
21d50 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
21d60 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
21d70 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
21d80 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
21d90 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
21da0 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
21db0 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
21dc0 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
21dd0 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
21de0 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
21df0 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
21e00 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
21e10 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
21e20 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
21e30 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
21e40 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
21e50 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c  .** ^On windows,
21e60 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
21e70 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
21e80 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
21e90 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
21ea0 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
21eb0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )..**.** [[core 
21ec0 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
21ed0 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
21ee0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
21ef0 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
21f00 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
21f10 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
21f20 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
21f30 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
21f40 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
21f50 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
21f60 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
21f70 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
21f80 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
21f90 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ee query paramet
21fa0 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
21fb0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
21fc0 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
21fd0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
21fe0 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
21ff0 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
22000 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
22010 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
22020 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
22030 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
22040 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
22050 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
22060 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
22070 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
22080 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
22090 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
220a0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
220b0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
220c0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
220d0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
220e0 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
220f0 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
22100 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
22110 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
22120 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
22130 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
22140 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
22150 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
22160 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
22170 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
22180 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
22190 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
221a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
221b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
221c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
221d0 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
221e0 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
221f0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
22200 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
22210 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
22220 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
22230 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
22240 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
22250 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
22260 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
22270 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
22280 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
22290 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
222a0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
222b0 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
222c0 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
222d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
222e0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
222f0 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
22300 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
22310 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
22320 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22330 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
22340 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
22350 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
22360 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
22370 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
22380 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
22390 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
223a0 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
223b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
223c0 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
223d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
223e0 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
223f0 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
22400 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
22410 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
22420 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
22430 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
22440 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
22450 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
22460 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
22470 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
22480 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
22490 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
224a0 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
224b0 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
224c0 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
224d0 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
224e0 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
224f0 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
22500 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
22510 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
22520 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
22530 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
22540 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
22550 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
22560 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
22570 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
22580 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
22590 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
225a0 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
225b0 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
225c0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
225d0 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
225e0 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
225f0 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
22600 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
22610 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
22620 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
22630 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
22640 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
22650 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
22660 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
22670 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
22680 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
22690 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
226a0 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
226b0 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
226c0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
226d0 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
226e0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
226f0 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
22700 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
22710 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
22720 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
22730 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
22740 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
22750 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
22760 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
22770 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
22780 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
22790 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
227a0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
227b0 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
227c0 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
227d0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
227e0 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20  >psow</b>: ^The 
227f0 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 6d  psow parameter m
22800 61 79 20 62 65 20 22 74 72 75 65 22 20 28 6f 72  ay be "true" (or
22810 20 22 6f 6e 22 20 6f 72 20 22 79 65 73 22 20 6f   "on" or "yes" o
22820 72 0a 2a 2a 20 20 20 20 20 22 31 22 29 20 6f 72  r.**     "1") or
22830 20 22 66 61 6c 73 65 22 20 28 6f 72 20 22 6f 66   "false" (or "of
22840 66 22 20 6f 72 20 22 6e 6f 22 20 6f 72 20 22 30  f" or "no" or "0
22850 22 29 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ") to indicate t
22860 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  hat the.**     [
22870 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
22880 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
22890 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
228a0 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
228b0 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
228c0 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
228d0 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
228e0 64 65 73 2e 20 20 5e 54 68 65 20 70 73 6f 77 20  des.  ^The psow 
228f0 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72  query.**     par
22900 61 6d 65 74 65 72 20 6f 6e 6c 79 20 77 6f 72 6b  ameter only work
22910 73 20 66 6f 72 20 74 68 65 20 62 75 69 6c 74 2d  s for the built-
22920 69 6e 20 75 6e 69 78 20 61 6e 64 20 57 69 6e 64  in unix and Wind
22930 6f 77 73 20 56 46 53 65 73 2e 0a 2a 2a 0a 2a 2a  ows VFSes..**.**
22940 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
22950 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
22960 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
22970 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
22980 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
22990 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
229a0 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
229b0 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
229c0 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
229d0 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
229e0 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
229f0 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
22a00 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
22a10 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
22a20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
22a30 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
22a40 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
22a50 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
22a60 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
22a70 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
22a80 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
22a90 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
22aa0 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
22ab0 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
22ac0 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
22ad0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
22ae0 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
22af0 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
22b00 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
22b10 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
22b20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
22b30 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
22b40 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22b50 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
22b60 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
22b70 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
22b80 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
22b90 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
22ba0 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
22bb0 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
22bc0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
22bd0 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
22be0 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
22bf0 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
22c00 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
22c10 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
22c20 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
22c30 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
22c40 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
22c50 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
22c60 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
22c70 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
22c80 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
22c90 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
22ca0 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
22cb0 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
22cc0 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
22cd0 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
22ce0 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
22cf0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
22d00 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
22d10 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
22d20 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
22d30 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
22d40 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
22d50 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
22d60 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
22d70 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
22d80 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
22d90 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
22da0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
22db0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
22dc0 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
22dd0 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
22de0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
22df0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
22e00 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
22e10 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
22e20 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
22e30 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22e40 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
22e50 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
22e60 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
22e70 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
22e80 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
22e90 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
22ea0 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
22eb0 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
22ec0 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
22ed0 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
22ee0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
22ef0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
22f00 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
22f10 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
22f20 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
22f30 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
22f40 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
22f50 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
22f60 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
22f70 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
22f80 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
22f90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
22fa0 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
22fb0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
22fc0 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
22fd0 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
22fe0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
22ff0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23000 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
23010 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
23020 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23030 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
23040 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
23050 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
23060 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
23070 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
23080 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
23090 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
230a0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
230b0 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
230c0 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
230d0 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
230e0 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
230f0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
23100 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
23110 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
23120 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
23130 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
23140 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
23150 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
23160 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
23170 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
23180 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
23190 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
231a0 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
231b0 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
231c0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
231d0 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
231e0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
231f0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
23200 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
23210 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
23220 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
23230 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
23240 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
23250 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
23260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
23270 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
23280 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
23290 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
232a0 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
232b0 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
232c0 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
232d0 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
232e0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
232f0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
23300 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
23310 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
23320 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
23330 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
23340 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
23350 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
23360 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
23370 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
23380 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
23390 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
233a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
233b0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
233c0 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
233d0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
233e0 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
233f0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
23400 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
23410 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
23420 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
23430 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
23440 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
23450 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
23460 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
23470 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
23480 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
23490 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
234a0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
234b0 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
234c0 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
234d0 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
234e0 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
234f0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
23500 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
23510 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
23520 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
23530 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
23540 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
23550 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
23560 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
23570 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
23580 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
23590 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
235a0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
235b0 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
235c0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
235d0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
235e0 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
235f0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
23600 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
23610 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
23620 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
23630 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
23640 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
23650 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
23660 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
23670 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
23680 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
23690 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
236a0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
236b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
236c0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
236d0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
236e0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
236f0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
23700 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
23710 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
23720 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
23730 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
23740 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
23750 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
23760 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
23770 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23780 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
23790 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
237a0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
237b0 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
237c0 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
237d0 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
237e0 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
237f0 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
23800 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
23810 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
23820 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
23830 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
23840 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
23850 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
23860 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
23870 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
23880 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
23890 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
238a0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
238b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
238c0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
238d0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
238e0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
238f0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
23900 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
23910 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
23920 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
23930 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
23940 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
23950 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
23960 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
23970 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
23980 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
23990 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
239a0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
239b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
239c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
239d0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
239e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
239f0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
23a00 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
23a10 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
23a20 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
23a30 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
23a40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
23a50 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
23a60 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
23a70 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
23a80 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
23a90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23aa0 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
23ab0 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
23ac0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
23ad0 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
23ae0 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
23af0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
23b00 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
23b10 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
23b20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
23b30 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
23b40 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
23b50 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
23b60 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
23b70 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
23b80 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
23b90 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
23ba0 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
23bb0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
23bc0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
23bd0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
23be0 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
23bf0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
23c00 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
23c10 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
23c20 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
23c30 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
23c40 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
23c50 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
23c60 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
23c70 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
23c80 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
23c90 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
23ca0 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
23cb0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
23cc0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
23cd0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
23ce0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
23cf0 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
23d00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
23d10 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
23d20 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
23d30 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
23d40 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
23d50 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
23d60 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
23d70 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
23d80 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
23d90 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
23da0 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
23db0 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
23dc0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
23dd0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
23de0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
23df0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
23e00 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
23e10 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
23e20 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
23e30 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
23e40 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
23e50 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
23e60 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
23e70 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
23e80 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
23e90 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
23ea0 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
23eb0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
23ec0 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
23ed0 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
23ee0 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
23ef0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
23f00 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
23f10 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
23f20 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
23f30 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
23f40 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
23f50 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
23f60 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
23f70 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
23f80 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
23f90 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
23fa0 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
23fb0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
23fc0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
23fd0 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
23fe0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
23ff0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
24000 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
24010 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
24020 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
24030 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
24040 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
24050 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
24060 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
24070 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
24080 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
24090 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
240a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
240b0 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
240c0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
240d0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
240e0 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
240f0 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
24100 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
24110 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
24120 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
24130 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
24140 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
24150 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
24160 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
24170 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
24180 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
24190 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
241a0 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
241b0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
241c0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
241d0 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
241e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
241f0 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
24200 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
24210 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
24220 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
24230 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
24240 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
24250 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
24260 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
24270 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
24280 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
24290 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
242a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
242b0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
242c0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
242d0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
242e0 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
242f0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
24300 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
24310 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
24320 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
24330 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
24340 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
24350 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
24360 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
24370 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
24380 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
24390 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
243a0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
243b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
243c0 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
243d0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
243e0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
243f0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
24400 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
24410 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
24420 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
24430 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
24440 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
24450 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
24460 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
24470 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
24480 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
24490 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
244a0 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
244b0 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
244c0 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
244d0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
244e0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
244f0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
24500 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
24510 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
24520 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
24530 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
24540 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
24550 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
24560 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
24570 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
24580 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
24590 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
245a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
245b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
245c0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
245d0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
245e0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
245f0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
24600 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
24610 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
24620 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
24630 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
24640 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
24650 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
24660 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
24670 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
24680 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
24690 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
246a0 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
246b0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
246c0 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
246d0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
246e0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
246f0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
24700 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
24710 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
24720 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
24730 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
24740 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
24750 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24760 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
24770 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
24780 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
24790 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
247a0 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
247b0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
247c0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
247d0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
247e0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
247f0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
24800 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
24810 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
24820 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
24830 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
24840 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
24850 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
24860 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
24870 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
24880 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
24890 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
248a0 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
248b0 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
248c0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
248d0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
248e0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
248f0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
24900 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
24910 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
24920 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
24930 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
24940 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
24950 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
24960 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
24970 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
24980 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
24990 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
249a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
249b0 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
249c0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
249d0 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
249e0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
249f0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
24a00 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
24a10 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
24a20 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
24a30 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
24a40 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
24a50 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
24a60 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
24a70 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
24a80 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
24a90 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
24aa0 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
24ab0 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
24ac0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
24ad0 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
24ae0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
24af0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
24b00 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
24b10 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
24b20 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
24b30 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
24b40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24b50 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
24b60 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
24b70 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
24b80 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
24b90 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24ba0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
24bb0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
24bc0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
24bd0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
24be0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
24bf0 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
24c00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24c10 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
24c20 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
24c30 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
24c40 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
24c50 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
24c60 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
24c70 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
24c80 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
24c90 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
24ca0 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
24cb0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
24cc0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
24cd0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
24ce0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
24cf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
24d00 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
24d10 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
24d20 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
24d30 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
24d40 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
24d50 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
24d60 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
24d70 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
24d80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
24d90 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
24da0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
24db0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
24dc0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
24dd0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
24de0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
24df0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
24e00 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
24e10 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
24e20 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
24e30 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
24e40 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
24e50 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
24e60 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
24e70 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24e80 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
24e90 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
24ea0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
24eb0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
24ec0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
24ed0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
24ee0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24ef0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
24f00 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
24f10 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
24f20 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
24f30 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
24f40 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
24f50 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
24f60 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
24f70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
24f80 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
24f90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
24fa0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
24fb0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
24fc0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
24fd0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
24fe0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
24ff0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
25000 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
25010 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
25020 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
25030 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
25040 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25050 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
25060 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
25070 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
25080 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
25090 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
250a0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
250b0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
250c0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
250d0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
250e0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
250f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
25100 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
25110 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
25120 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
25130 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
25140 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
25150 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
25160 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
25170 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
25180 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
25190 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
251a0 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
251b0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
251c0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
251d0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
251e0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
251f0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
25200 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
25210 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
25220 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
25230 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
25240 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
25250 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
25260 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
25270 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
25280 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
25290 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
252a0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
252b0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
252c0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
252d0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
252e0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
252f0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
25300 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
25310 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
25320 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
25330 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
25340 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
25350 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
25360 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
25370 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
25380 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
25390 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
253a0 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
253b0 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
253c0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
253d0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
253e0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
253f0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
25400 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
25410 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
25420 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
25430 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
25440 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
25450 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
25460 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
25470 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
25480 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
25490 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
254a0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
254b0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
254c0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
254d0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
254e0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
254f0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
25500 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
25510 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
25520 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
25530 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
25540 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
25550 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
25560 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
25570 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
25580 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
25590 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
255a0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
255b0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
255c0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
255d0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
255e0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
255f0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
25600 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
25610 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
25620 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
25630 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
25640 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
25650 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
25660 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
25670 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
25680 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
25690 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
256a0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
256b0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
256c0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
256d0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
256e0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
256f0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
25700 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
25710 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
25720 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
25730 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
25740 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
25750 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
25760 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
25770 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
25780 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
25790 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
257a0 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
257b0 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
257c0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
257d0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
257e0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
257f0 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
25800 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
25810 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
25820 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
25830 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
25840 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
25850 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
25860 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
25870 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
25880 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
25890 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
258a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
258b0 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
258c0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
258d0 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
258e0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
258f0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
25900 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25910 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
25920 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25930 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
25940 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
25950 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
25960 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
25970 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
25980 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
25990 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
259a0 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
259b0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
259c0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
259d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
259e0 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
259f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25a00 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
25a10 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25a20 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
25a30 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
25a40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
25a50 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
25a60 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
25a70 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
25a80 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
25a90 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
25aa0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
25ab0 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
25ac0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
25ad0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
25ae0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
25af0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
25b00 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
25b10 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
25b20 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
25b30 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25b40 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
25b50 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
25b60 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
25b70 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25b80 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
25b90 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
25ba0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
25bb0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
25bc0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25bd0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25be0 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
25bf0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
25c00 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
25c10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25c20 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
25c30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
25c40 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
25c50 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
25c60 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
25c70 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
25c80 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
25c90 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
25ca0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
25cb0 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
25cc0 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
25cd0 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
25ce0 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
25cf0 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
25d00 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
25d10 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
25d20 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
25d30 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25d40 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
25d50 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25d60 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
25d70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25d80 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25d90 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
25da0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
25db0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25dc0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
25dd0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25de0 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
25df0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25e00 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
25e10 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
25e20 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
25e30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
25e40 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
25e50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
25e60 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
25e70 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
25e80 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
25e90 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25ea0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
25eb0 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
25ec0 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
25ed0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
25ee0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
25ef0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25f00 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
25f10 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
25f20 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
25f30 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
25f40 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25f50 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
25f60 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
25f70 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
25f80 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
25f90 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
25fa0 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
25fb0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25fc0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
25fd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25fe0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
25ff0 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
26000 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
26010 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
26020 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26030 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
26040 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
26050 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26060 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
26070 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
26080 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26090 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
260a0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
260b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
260c0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
260d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
260e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
260f0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
26100 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
26110 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26120 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
26130 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26140 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
26150 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
26160 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
26170 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
26180 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
26190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
261a0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
261b0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
261c0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
261d0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
261e0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
261f0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
26200 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
26210 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
26220 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
26230 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41      10../*.** CA
26240 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
26250 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
26260 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
26270 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
26280 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
26290 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
262a0 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
262b0 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
262c0 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
262d0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
262e0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
262f0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
26300 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
26310 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
26320 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
26330 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
26340 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
26350 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
26360 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
26370 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
26380 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
26390 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
263a0 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
263b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
263c0 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
263d0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
263e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
263f0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
26400 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
26410 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
26420 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
26430 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
26440 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
26450 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
26460 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
26470 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
26480 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
26490 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
264a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
264b0 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
264c0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
264d0 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
264e0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
264f0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
26500 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
26510 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
26520 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
26530 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f   ^If nByte is no
26540 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
26550 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
26560 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
26570 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
26580 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42   zSql.  ^When nB
26590 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
265a0 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
265b0 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
265c0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
265d0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
265e0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
265f0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
26600 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
26610 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
26620 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
26630 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
26640 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
26650 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
26660 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
26670 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
26680 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
26690 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
266a0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
266b0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
266c0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
266d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
266e0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
266f0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
26700 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
26710 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
26720 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65  tes as this save
26730 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61  s SQLite from ha
26740 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20  ving to.** make 
26750 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e  a copy of the in
26760 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  put string..**.*
26770 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
26780 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
26790 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
267a0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
267b0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
267c0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
267d0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
267e0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
267f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
26800 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
26810 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
26820 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
26830 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
26840 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
26850 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
26860 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
26870 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
26880 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
26890 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
268a0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
268b0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
268c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
268d0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
268e0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
268f0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
26900 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
26910 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
26920 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
26930 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
26940 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
26950 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
26960 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
26970 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
26980 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
26990 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
269a0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
269b0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
269c0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
269d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
269e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
269f0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
26a00 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
26a10 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
26a20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
26a30 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
26a40 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
26a50 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
26a60 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
26a70 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
26a80 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
26a90 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
26aa0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26ab0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
26ac0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26ad0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
26ae0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
26af0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
26b00 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
26b10 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
26b20 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
26b30 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
26b40 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
26b50 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
26b60 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
26b70 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
26b80 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
26b90 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
26ba0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
26bb0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
26bc0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
26bd0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
26be0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
26bf0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
26c00 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
26c10 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
26c20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
26c30 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
26c40 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
26c50 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
26c60 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
26c70 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
26c80 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
26c90 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
26ca0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
26cb0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
26cc0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
26cd0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
26ce0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
26cf0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
26d00 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
26d10 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
26d20 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
26d30 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
26d40 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
26d50 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
26d60 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
26d70 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
26d80 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
26d90 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
26da0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
26db0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
26dc0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
26dd0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
26de0 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
26df0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
26e00 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
26e10 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
26e20 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
26e30 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
26e40 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
26e50 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
26e60 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
26e70 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
26e80 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
26e90 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
26ea0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
26eb0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
26ec0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26ed0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
26ee0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
26ef0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
26f00 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
26f10 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
26f20 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
26f30 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
26f40 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
26f50 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
26f60 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
26f70 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
26f80 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
26f90 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
26fa0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
26fb0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
26fc0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
26fd0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
26fe0 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
26ff0 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
27000 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
27010 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
27020 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
27030 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
27040 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
27050 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
27060 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
27070 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
27080 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
27090 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
270a0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
270b0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
270c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
270d0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
270e0 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
270f0 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
27100 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
27110 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
27120 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
27130 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
27140 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
27150 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
27160 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
27170 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
27180 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
27190 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
271a0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
271b0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
271c0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
271d0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
271e0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
271f0 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
27200 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
27210 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
27220 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
27230 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
27240 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
27250 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
27260 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
27270 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
27280 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
27290 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
272a0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
272b0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
272c0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
272d0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
272e0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
272f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
27300 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27310 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
27320 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
27330 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27340 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
27350 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
27360 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
27370 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27380 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
27390 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
273a0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
273b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
273c0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
273d0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
273e0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
273f0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
27400 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
27410 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27420 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
27430 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
27440 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
27450 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
27460 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27470 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
27480 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
27490 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
274a0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
274b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
274c0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
274d0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
274e0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
274f0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27500 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
27510 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
27520 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
27530 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
27540 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
27550 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
27560 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
27570 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
27580 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
27590 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
275a0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
275b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
275c0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
275d0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
275e0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
275f0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
27600 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27610 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
27620 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
27630 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
27640 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
27650 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
27660 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
27670 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
27680 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
27690 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
276a0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
276b0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
276c0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
276d0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
276e0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
276f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
27700 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
27710 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
27720 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
27730 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
27740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27750 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
27760 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
27770 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
27780 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
27790 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
277a0 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
277b0 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
277c0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
277d0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
277e0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
277f0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
27800 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
27810 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
27820 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
27830 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
27840 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
27850 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27860 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
27870 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
27880 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
27890 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
278a0 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
278b0 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
278c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
278d0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
278e0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
278f0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
27900 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
27910 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
27920 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27930 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
27940 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
27950 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
27960 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27970 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
27980 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
27990 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
279a0 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
279b0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
279c0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
279d0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
279e0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
279f0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
27a00 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
27a10 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
27a20 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
27a30 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
27a40 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
27a50 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
27a60 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
27a70 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
27a80 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
27a90 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
27aa0 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
27ab0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
27ac0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
27ad0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
27ae0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
27af0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
27b00 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
27b10 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
27b20 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
27b30 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
27b40 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
27b50 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
27b60 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
27b70 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
27b80 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
27b90 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
27ba0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
27bb0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
27bc0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
27bd0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
27be0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
27bf0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
27c00 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
27c10 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
27c20 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
27c30 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
27c40 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
27c50 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
27c60 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
27c70 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
27c80 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
27c90 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
27ca0 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
27cb0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
27cc0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
27cd0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
27ce0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
27cf0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
27d00 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
27d10 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
27d20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
27d30 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
27d40 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
27d50 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
27d60 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
27d70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
27d80 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
27d90 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
27da0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
27db0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27dc0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
27dd0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
27de0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
27df0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
27e10 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
27e20 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
27e30 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
27e40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27e50 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
27e60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27e70 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
27e80 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
27e90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27ea0 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
27eb0 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
27ec0 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
27ed0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
27ee0 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f  t has not run to
27ef0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f   completion and/
27f00 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62  or has not .** b
27f10 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
27f20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
27f30 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
27f40 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
27f50 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
27f60 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
27f70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
27f80 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
27f90 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
27fa0 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
27fb0 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
27fc0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
27fd0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
27fe0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
27ff0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
28000 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
28010 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
28020 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
28030 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
28040 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
28050 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
28060 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
28070 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
28080 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
28090 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
280a0 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
280b0 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
280c0 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
280d0 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
280e0 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
280f0 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
28100 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
28110 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
28120 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
28130 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
28140 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
28150 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  open..*/.int sql
28160 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
28170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
28180 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28190 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
281a0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
281b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
281c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
281d0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
281e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
281f0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
28200 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
28210 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
28220 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
28230 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
28240 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
28250 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
28260 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
28270 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
28280 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
28290 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
282a0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
282b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
282c0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
282d0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
282e0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
282f0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
28300 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
28310 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28320 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
28330 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
28340 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
28350 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
28360 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
28370 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28380 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
28390 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
283a0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
283b0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
283c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
283d0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
283e0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
283f0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
28400 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
28410 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
28420 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
28430 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
28440 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28450 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
28460 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
28470 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
28480 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
28490 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
284a0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
284b0 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
284c0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
284d0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
284e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
284f0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
28500 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
28510 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
28520 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28530 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
28540 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
28550 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
28560 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
28570 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
28580 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
28590 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
285a0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
285b0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
285c0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
285d0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
285e0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
285f0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
28600 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
28610 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
28620 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
28630 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
28640 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
28650 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
28660 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
28670 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
28680 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
28690 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
286a0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
286b0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
286c0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
286d0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
286e0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
286f0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
28700 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
28710 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
28720 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
28730 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28740 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
28750 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
28760 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
28770 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
28780 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
28790 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
287a0 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
287b0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
287c0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
287d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
287e0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
287f0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
28800 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
28810 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
28820 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
28830 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
28840 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
28850 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
28860 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28870 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
28880 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
28890 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
288a0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
288b0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
288c0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
288d0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
288e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
288f0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
28900 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
28910 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
28920 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28930 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
28940 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
28950 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
28960 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
28970 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
28980 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
28990 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
289a0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
289b0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
289c0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
289d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
289e0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
289f0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
28a00 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
28a10 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
28a20 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
28a30 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
28a40 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28a50 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
28a60 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28a70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
28a80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
28a90 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
28aa0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
28ab0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
28ac0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
28ad0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
28ae0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
28af0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
28b00 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
28b10 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
28b20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
28b30 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
28b40 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
28b50 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
28b60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
28b70 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
28b80 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
28b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
28ba0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
28bb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28bc0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
28bd0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
28be0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
28bf0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
28c00 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
28c10 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
28c20 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
28c30 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
28c40 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
28c50 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
28c60 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
28c70 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
28c80 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
28c90 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
28ca0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28cb0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
28cc0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
28cd0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
28ce0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
28cf0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
28d00 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
28d10 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
28d20 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
28d30 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
28d40 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
28d50 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
28d60 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
28d70 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
28d80 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
28d90 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
28da0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
28db0 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
28dc0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
28dd0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
28de0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
28df0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
28e00 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
28e10 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
28e20 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
28e30 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
28e40 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
28e50 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
28e60 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
28e70 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
28e80 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
28e90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
28ea0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
28eb0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
28ec0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
28ed0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
28ee0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
28ef0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
28f00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
28f10 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
28f20 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
28f30 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
28f40 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
28f50 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
28f60 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
28f70 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
28f80 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
28f90 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
28fa0 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
28fb0 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
28fc0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
28fd0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
28fe0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
28ff0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
29000 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
29010 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
29020 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
29030 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
29040 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
29050 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
29060 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
29070 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
29080 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29090 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
290a0 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
290b0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
290c0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
290d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
290e0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
290f0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
29100 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
29110 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
29120 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
29130 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
29140 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
29150 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
29160 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
29170 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
29180 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
29190 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
291a0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
291b0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
291c0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
291d0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
291e0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
291f0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
29200 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
29210 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
29220 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
29230 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
29240 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
29250 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
29260 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
29270 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
29280 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
29290 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
292a0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
292b0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
292c0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
292d0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
292e0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
292f0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
29300 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
29310 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
29320 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
29330 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
29340 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
29350 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
29360 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
29370 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
29380 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
29390 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
293a0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
293b0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
293c0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
293d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
293e0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
293f0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
29400 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
29410 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
29420 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
29430 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
29440 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
29450 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
29460 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
29470 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
29480 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
29490 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
294a0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
294b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
294c0 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74  _text16() then t
294d0 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
294e0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
294f0 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
29500 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
29510 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
29520 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
29530 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
29540 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
29550 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
29560 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
29570 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
29580 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
29590 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
295a0 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
295b0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
295c0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
295d0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
295e0 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
295f0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
29600 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
29610 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
29620 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
29630 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
29640 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
29650 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29660 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
29670 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
29680 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
29690 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
296a0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
296b0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
296c0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
296d0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
296e0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
296f0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
29700 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
29710 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
29720 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
29730 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
29740 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
29750 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a  3_bind_blob(),.*
29760 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
29770 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  ext(), or sqlite
29780 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
29790 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20  fails.  .** ^If 
297a0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
297b0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
297c0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
297d0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
297e0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
297f0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
29800 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
29810 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
29820 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
29830 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
29840 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
29850 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
29860 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
29870 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
29880 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
29890 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
298a0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
298b0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
298c0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
298d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
298e0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
298f0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
29900 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
29910 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
29920 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
29930 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
29940 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
29950 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
29960 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
29970 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
29980 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
29990 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
299a0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
299b0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
299c0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
299d0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
299e0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
299f0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
29a00 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
29a10 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
29a20 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
29a30 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
29a40 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
29a50 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
29a60 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
29a70 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
29a80 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
29a90 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
29aa0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
29ab0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
29ac0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
29ad0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
29ae0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
29af0 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
29b00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29b10 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
29b20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29b30 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
29b40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29b50 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
29b60 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
29b70 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
29b80 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
29b90 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
29ba0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
29bb0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
29bc0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
29bd0 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
29be0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
29bf0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
29c00 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
29c10 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
29c20 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
29c30 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
29c40 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
29c50 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
29c60 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
29c70 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
29c80 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
29c90 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
29ca0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
29cb0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
29cc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
29cd0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
29ce0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
29cf0 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
29d00 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
29d10 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
29d20 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
29d30 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
29d40 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
29d50 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
29d60 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
29d70 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
29d80 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
29d90 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
29da0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
29db0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29dc0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
29dd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29de0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
29df0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
29e00 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
29e10 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
29e20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29e30 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
29e40 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
29e50 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
29e60 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
29e70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
29e80 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
29e90 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
29ea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29eb0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
29ec0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
29ed0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29ee0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
29ef0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
29f00 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
29f10 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
29f20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29f30 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
29f40 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
29f50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
29f60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
29f70 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
29f80 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
29f90 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
29fa0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29fb0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
29fc0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
29fd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
29fe0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
29ff0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2a000 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
2a010 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2a020 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
2a030 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a040 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
2a050 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2a060 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
2a070 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
2a080 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2a090 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
2a0a0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
2a0b0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
2a0c0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2a0d0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
2a0e0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
2a0f0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
2a100 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
2a110 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
2a120 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
2a130 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
2a140 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
2a150 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
2a160 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2a170 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
2a180 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
2a190 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
2a1a0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2a1b0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
2a1c0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
2a1d0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
2a1e0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
2a1f0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
2a200 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
2a210 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
2a220 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
2a230 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
2a240 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
2a250 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
2a260 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
2a270 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
2a280 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
2a290 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
2a2a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2a2b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2a2c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2a2d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a2e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2a2f0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2a300 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a310 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2a320 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a330 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2a340 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
2a350 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a360 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
2a370 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
2a380 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2a390 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2a3a0 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
2a3b0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
2a3c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
2a3d0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
2a3e0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
2a3f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2a400 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
2a410 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2a420 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2a430 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2a440 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
2a450 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
2a460 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
2a470 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2a480 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2a490 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2a4a0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2a4b0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
2a4c0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
2a4d0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
2a4e0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
2a4f0 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
2a500 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
2a510 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
2a520 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
2a530 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
2a540 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
2a550 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
2a560 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
2a570 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
2a580 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
2a590 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
2a5a0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2a5b0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
2a5c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
2a5d0 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
2a5e0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
2a5f0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
2a600 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
2a610 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
2a620 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
2a630 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
2a640 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
2a650 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
2a660 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
2a670 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
2a680 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
2a690 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
2a6a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a6b0 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
2a6c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2a6d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2a6e0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2a6f0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2a700 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2a710 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a720 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2a730 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2a740 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2a750 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
2a760 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
2a770 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2a780 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a790 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
2a7a0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
2a7b0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
2a7c0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
2a7d0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2a7e0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
2a7f0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
2a800 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
2a810 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
2a820 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
2a830 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
2a840 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
2a850 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2a860 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2a870 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
2a880 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
2a890 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
2a8a0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
2a8b0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
2a8c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
2a8d0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
2a8e0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
2a8f0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2a900 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
2a910 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
2a920 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
2a930 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a940 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2a950 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2a960 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2a970 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2a980 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a990 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2a9a0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2a9b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a9c0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2a9d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2a9e0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2a9f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2aa00 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2aa10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2aa20 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2aa30 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2aa40 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2aa50 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2aa60 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2aa70 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2aa80 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2aa90 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2aaa0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2aab0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2aac0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2aad0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2aae0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2aaf0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2ab00 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2ab10 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
2ab20 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2ab30 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2ab40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ab50 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2ab60 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2ab70 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
2ab80 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2ab90 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2aba0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2abb0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2abc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2abd0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2abe0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2abf0 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2ac00 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2ac10 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2ac20 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2ac30 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2ac40 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2ac50 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2ac60 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2ac70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2ac80 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2ac90 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2aca0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2acb0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2acc0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2acd0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2ace0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2acf0 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2ad00 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2ad10 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2ad20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2ad30 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2ad40 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2ad50 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2ad60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2ad70 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2ad80 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2ad90 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2ada0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2adb0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2adc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2add0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2ade0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2adf0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2ae00 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2ae10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ae20 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2ae30 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2ae40 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2ae50 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2ae60 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2ae70 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2ae80 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2ae90 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2aea0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2aeb0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2aec0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2aed0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2aee0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aef0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2af00 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2af10 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2af20 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2af30 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2af40 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2af50 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2af60 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2af70 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2af80 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2af90 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2afa0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2afb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2afc0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2afd0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2afe0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2aff0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2b000 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2b010 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2b020 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2b030 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2b040 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2b050 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2b060 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2b070 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2b080 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2b090 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2b0a0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2b0b0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2b0c0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2b0d0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2b0e0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2b0f0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2b100 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2b110 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2b120 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2b130 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2b140 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2b150 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2b160 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2b170 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2b180 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
2b190 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2b1a0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
2b1b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b1c0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
2b1d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b1e0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2b1f0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
2b200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2b210 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
2b220 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2b230 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2b240 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2b250 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2b260 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2b270 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2b280 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2b290 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2b2a0 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2b2b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2b2c0 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2b2d0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2b2e0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2b2f0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2b300 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2b310 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2b320 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2b330 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2b340 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2b350 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2b360 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2b370 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2b380 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2b390 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2b3a0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2b3b0 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2b3c0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2b3d0 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2b3e0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2b3f0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2b400 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b410 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2b420 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2b430 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2b440 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2b450 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2b460 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2b470 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2b480 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2b490 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2b4a0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2b4b0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2b4c0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2b4d0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2b4e0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2b4f0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2b500 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2b510 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2b520 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2b530 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2b540 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2b550 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2b560 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2b570 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2b580 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2b590 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2b5a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2b5b0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2b5c0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2b5d0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2b5e0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2b5f0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2b600 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2b610 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2b620 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2b630 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2b640 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2b650 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2b660 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2b670 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2b680 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2b690 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2b6a0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2b6b0 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2b6c0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2b6d0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2b6e0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2b6f0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2b700 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2b710 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2b720 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2b730 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2b740 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2b750 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2b760 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2b770 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2b780 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2b790 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2b7a0 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2b7b0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2b7c0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2b7d0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2b7e0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2b7f0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2b800 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2b810 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2b820 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2b830 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2b840 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2b850 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2b860 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2b870 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2b880 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2b890 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2b8a0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2b8b0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2b8c0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2b8d0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2b8e0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2b8f0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2b900 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2b910 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2b920 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2b930 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2b940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2b950 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2b960 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2b970 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2b980 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2b990 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2b9a0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2b9b0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2b9c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2b9d0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2b9e0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2b9f0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2ba00 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2ba10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2ba20 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2ba30 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2ba40 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2ba50 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2ba60 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
2ba70 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2ba80 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2ba90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2baa0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2bab0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2bac0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_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 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2baf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bb00 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2bb10 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2bb20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2bb30 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2bb40 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2bb50 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2bb60 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2bb70 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2bb80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2bb90 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2bba0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2bbb0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2bbc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2bbd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bbe0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2bbf0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2bc00 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
2bc10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2bc20 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2bc30 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2bc40 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2bc50 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2bc60 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2bc70 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2bc80 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2bc90 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2bca0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2bcb0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2bcc0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2bcd0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2bce0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2bcf0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2bd00 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2bd10 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2bd20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2bd30 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2bd40 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2bd50 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2bd60 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2bd70 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2bd80 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2bd90 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2bda0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2bdb0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2bdc0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2bdd0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2bde0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2bdf0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2be00 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2be10 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2be20 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2be30 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2be40 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2be50 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2be60 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2be70 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2be80 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2be90 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2bea0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2beb0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2bec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2bed0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2bee0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2bef0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2bf00 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2bf10 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2bf20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2bf30 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2bf40 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2bf50 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2bf60 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2bf70 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2bf80 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2bf90 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2bfa0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2bfb0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2bfc0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2bfd0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2bfe0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2bff0 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2c000 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2c010 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2c020 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2c030 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2c040 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2c050 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2c060 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2c070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2c080 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
2c090 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2c0a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c0b0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
2c0c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2c0d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2c0e0 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
2c0f0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2c100 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2c110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c120 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2c130 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2c140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2c150 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2c160 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c170 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2c180 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2c190 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2c1a0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2c1b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c1c0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2c1d0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2c1e0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2c1f0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2c200 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2c210 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2c220 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2c230 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2c240 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2c250 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2c260 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2c270 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2c280 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2c290 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2c2a0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2c2b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c2c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2c2d0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2c2e0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2c2f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2c300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2c310 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2c320 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2c330 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2c340 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2c350 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2c360 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2c370 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2c380 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2c390 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2c3a0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2c3b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2c3c0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2c3d0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2c3e0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2c3f0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2c400 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2c410 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2c420 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2c430 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2c440 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2c450 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2c460 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2c470 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2c480 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2c490 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2c4a0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2c4b0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2c4c0 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2c4d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2c4e0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2c4f0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2c500 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2c510 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2c520 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2c530 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2c540 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2c550 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2c560 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2c570 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2c580 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2c590 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2c5a0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2c5b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2c5c0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2c5d0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2c5e0 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2c5f0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2c600 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2c610 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2c620 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2c630 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2c640 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2c650 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2c660 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2c670 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2c680 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2c690 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2c6a0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2c6b0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2c6c0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2c6d0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2c6e0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2c6f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2c700 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2c710 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2c720 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2c730 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2c740 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2c750 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2c760 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2c770 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2c780 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2c790 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2c7a0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2c7b0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2c7c0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2c7d0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2c7e0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2c7f0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2c800 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2c810 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2c820 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2c830 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
2c840 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
2c850 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
2c860 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2c870 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
2c880 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
2c890 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
2c8a0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
2c8b0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
2c8c0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
2c8d0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2c8e0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2c8f0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
2c900 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
2c910 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
2c920 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2c930 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
2c940 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
2c950 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
2c960 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2c970 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
2c980 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
2c990 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
2c9a0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
2c9b0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
2c9c0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
2c9d0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
2c9e0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2c9f0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
2ca00 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2ca10 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
2ca20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2ca30 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
2ca40 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2ca50 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2ca60 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
2ca70 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
2ca80 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
2ca90 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2caa0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
2cab0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
2cac0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
2cad0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
2cae0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
2caf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2cb00 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
2cb10 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
2cb20 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2cb30 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
2cb40 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
2cb50 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
2cb60 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
2cb70 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2cb80 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
2cb90 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
2cba0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2cbb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2cbc0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
2cbd0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
2cbe0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
2cbf0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
2cc00 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
2cc10 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2cc20 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
2cc30 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
2cc40 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2cc50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2cc60 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
2cc70 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
2cc80 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
2cc90 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
2cca0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
2ccb0 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
2ccc0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
2ccd0 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
2cce0 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
2ccf0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
2cd00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2cd10 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2cd20 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
2cd30 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
2cd40 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
2cd50 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
2cd60 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
2cd70 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
2cd80 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
2cd90 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
2cda0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
2cdb0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
2cdc0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
2cdd0 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
2cde0 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
2cdf0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2ce00 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
2ce10 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
2ce20 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
2ce30 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
2ce40 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
2ce50 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
2ce60 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
2ce70 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
2ce80 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
2ce90 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
2cea0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
2ceb0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
2cec0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
2ced0 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
2cee0 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
2cef0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
2cf00 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
2cf10 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
2cf20 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2cf30 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
2cf40 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
2cf50 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
2cf60 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
2cf70 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
2cf80 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
2cf90 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
2cfa0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
2cfb0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
2cfc0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
2cfd0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
2cfe0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2cff0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d000 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
2d010 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
2d020 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
2d030 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
2d040 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
2d050 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
2d060 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
2d070 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
2d080 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
2d090 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
2d0a0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
2d0b0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
2d0c0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
2d0d0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
2d0e0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
2d0f0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2d100 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2d110 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2d120 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
2d130 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
2d140 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
2d150 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2d160 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2d170 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
2d180 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
2d190 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2d1a0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
2d1b0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
2d1c0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2d1d0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2d1e0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2d1f0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
2d200 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2d210 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2d220 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2d230 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2d240 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2d250 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
2d260 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2d270 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
2d280 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
2d290 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2d2a0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
2d2b0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2d2c0 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
2d2d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d2e0 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
2d2f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2d300 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
2d310 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
2d320 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
2d330 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
2d340 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
2d350 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d360 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
2d370 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
2d380 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2d390 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
2d3a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2d3b0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2d3c0 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
2d3d0 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
2d3e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
2d3f0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2d400 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2d410 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
2d420 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2d430 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2d440 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
2d450 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2d460 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2d470 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
2d480 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
2d490 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
2d4a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2d4b0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2d4c0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
2d4d0 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
2d4e0 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
2d4f0 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
2d500 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
2d510 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
2d520 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
2d530 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
2d540 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
2d550 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
2d560 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
2d570 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2d580 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d590 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
2d5a0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2d5b0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2d5c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2d5d0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
2d5e0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
2d5f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
2d600 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
2d610 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
2d620 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
2d630 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
2d640 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
2d650 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2d660 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
2d670 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
2d680 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
2d690 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2d6a0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
2d6b0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
2d6c0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
2d6d0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
2d6e0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
2d6f0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
2d700 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
2d710 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
2d720 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
2d730 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
2d740 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
2d750 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
2d760 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
2d770 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
2d780 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
2d790 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
2d7a0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
2d7b0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
2d7c0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
2d7d0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
2d7e0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
2d7f0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
2d800 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
2d810 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
2d820 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
2d830 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
2d840 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
2d850 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
2d860 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
2d870 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
2d880 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
2d890 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2d8a0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
2d8b0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
2d8c0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
2d8d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2d8e0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
2d8f0 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
2d900 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
2d910 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
2d920 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2d930 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
2d940 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
2d950 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
2d960 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2d970 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2d980 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
2d990 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
2d9a0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
2d9b0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
2d9c0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
2d9d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2d9e0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
2d9f0 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
2da00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2da10 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
2da20 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
2da30 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
2da40 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2da50 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
2da60 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
2da70 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
2da80 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
2da90 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2daa0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2dab0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
2dac0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
2dad0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
2dae0 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
2daf0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
2db00 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
2db10 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
2db20 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
2db30 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2db40 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
2db50 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
2db60 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2db70 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
2db80 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2db90 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2dba0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
2dbb0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
2dbc0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
2dbd0 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
2dbe0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
2dbf0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2dc00 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
2dc10 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
2dc20 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
2dc30 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2dc40 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2dc50 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2dc60 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2dc70 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
2dc80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2dc90 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
2dca0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
2dcb0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
2dcc0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
2dcd0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
2dce0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2dcf0 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
2dd00 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2dd10 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2dd20 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
2dd30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2dd40 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
2dd50 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
2dd60 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2dd70 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
2dd80 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2dd90 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
2dda0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2ddb0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2ddc0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ddd0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
2dde0 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
2ddf0 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
2de00 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2de10 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
2de20 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2de30 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2de40 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2de50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2de60 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2de70 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2de80 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2de90 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2dea0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2deb0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2dec0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2ded0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2dee0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2def0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2df00 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2df10 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2df20 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2df30 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2df40 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2df50 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2df60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2df70 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2df80 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2df90 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2dfa0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2dfb0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2dfc0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2dfd0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2dfe0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2dff0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2e000 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2e010 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2e020 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2e030 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2e040 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2e050 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2e060 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2e070 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2e080 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2e090 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2e0a0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2e0b0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2e0c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2e0d0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2e0e0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2e0f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2e100 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2e110 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2e120 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2e130 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2e140 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2e150 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2e160 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2e170 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2e180 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2e190 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2e1a0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2e1b0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2e1c0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2e1d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e1e0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2e1f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2e200 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2e210 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2e220 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2e230 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2e240 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2e250 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2e260 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2e270 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2e280 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2e290 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2e2a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e2b0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2e2c0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2e2d0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2e2e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2e2f0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2e300 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2e310 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2e320 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2e330 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2e340 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2e350 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2e360 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e370 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2e380 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2e390 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2e3a0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2e3b0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2e3c0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2e3d0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2e3e0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2e3f0 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2e400 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2e410 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2e420 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2e430 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2e440 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2e450 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2e460 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2e470 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2e480 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2e490 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2e4a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2e4b0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2e4c0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2e4d0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2e4e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e4f0 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2e500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e510 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2e520 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2e530 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2e540 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2e550 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2e560 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2e570 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2e580 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e590 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
2e5a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e5b0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
2e5c0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2e5d0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2e5e0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2e5f0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2e600 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
2e610 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2e620 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2e630 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2e640 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2e650 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2e660 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2e670 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
2e680 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
2e690 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2e6a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2e6b0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
2e6c0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
2e6d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2e6e0 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
2e6f0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2e700 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2e710 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
2e720 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e730 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
2e740 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
2e750 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e760 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
2e770 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
2e780 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2e790 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2e7a0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2e7b0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
2e7c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e7d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2e7e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2e7f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2e800 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
2e810 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
2e820 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
2e830 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
2e840 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
2e850 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
2e860 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e870 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2e880 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2e890 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
2e8a0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2e8b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
2e8c0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
2e8d0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2e8e0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
2e8f0 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
2e900 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
2e910 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
2e920 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
2e930 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
2e940 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
2e950 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
2e960 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
2e970 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
2e980 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
2e990 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
2e9a0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
2e9b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
2e9c0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
2e9d0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
2e9e0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
2e9f0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2ea00 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2ea10 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2ea20 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
2ea30 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
2ea40 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
2ea50 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
2ea60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2ea70 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2ea80 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2ea90 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
2eaa0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
2eab0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
2eac0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
2ead0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2eae0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2eaf0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
2eb00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2eb10 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2eb20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2eb30 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2eb40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2eb50 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2eb60 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2eb70 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2eb80 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2eb90 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2eba0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2ebb0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2ebc0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2ebd0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2ebe0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2ebf0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2ec00 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2ec10 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2ec20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2ec30 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2ec40 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2ec50 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
2ec60 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2ec70 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2ec80 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2ec90 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
2eca0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2ecb0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2ecc0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2ecd0 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
2ece0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2ecf0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
2ed00 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
2ed10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2ed20 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
2ed30 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
2ed40 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
2ed50 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2ed60 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2ed70 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
2ed80 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2ed90 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2eda0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2edb0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2edc0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2edd0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2ede0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
2edf0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2ee00 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2ee10 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
2ee20 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
2ee30 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
2ee40 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
2ee50 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
2ee60 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
2ee70 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
2ee80 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
2ee90 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
2eea0 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
2eeb0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
2eec0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
2eed0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2eee0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
2eef0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
2ef00 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
2ef10 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
2ef20 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
2ef30 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
2ef40 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
2ef50 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
2ef60 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
2ef70 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
2ef80 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
2ef90 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
2efa0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
2efb0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
2efc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
2efd0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
2efe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2eff0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
2f000 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
2f010 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
2f020 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
2f030 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
2f040 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
2f050 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
2f060 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
2f070 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
2f080 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
2f090 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
2f0a0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
2f0b0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2f0c0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
2f0d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f0e0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2f0f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f100 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2f110 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
2f120 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
2f130 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
2f140 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
2f150 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2f160 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2f170 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
2f180 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2f190 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
2f1a0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2f1b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f1c0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2f1d0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2f1e0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2f1f0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
2f200 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2f210 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2f220 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
2f230 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2f240 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
2f250 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2f260 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
2f270 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2f280 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2f290 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2f2a0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
2f2b0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
2f2c0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
2f2d0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
2f2e0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
2f2f0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
2f300 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
2f310 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
2f320 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
2f330 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
2f340 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
2f350 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
2f360 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
2f370 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
2f380 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
2f390 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
2f3a0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
2f3b0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
2f3c0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
2f3d0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
2f3e0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
2f3f0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
2f400 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
2f410 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
2f420 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
2f430 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
2f440 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
2f450 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
2f460 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
2f470 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
2f480 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
2f490 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
2f4a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
2f4b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f4c0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
2f4d0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2f4e0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
2f4f0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2f500 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
2f510 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2f520 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2f530 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2f540 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2f550 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
2f560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f570 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
2f580 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2f590 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
2f5a0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
2f5b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f5c0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
2f5d0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
2f5e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f5f0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
2f600 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
2f610 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
2f620 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
2f630 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
2f640 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f650 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2f660 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f670 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
2f680 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
2f690 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
2f6a0 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
2f6b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2f6c0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2f6d0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
2f6e0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2f6f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2f700 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
2f710 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
2f720 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f730 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
2f740 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2f750 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
2f760 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
2f770 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2f780 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2f790 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2f7a0 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2f7b0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2f7c0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2f7d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2f7e0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2f7f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f800 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
2f810 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
2f820 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
2f830 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
2f840 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
2f850 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
2f860 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
2f870 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2f880 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
2f890 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2f8a0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
2f8b0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
2f8c0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
2f8d0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2f8e0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
2f8f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2f900 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2f910 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2f920 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2f930 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2f940 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2f950 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2f960 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2f970 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2f980 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2f990 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2f9a0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2f9b0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2f9c0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2f9d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2f9e0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2f9f0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2fa00 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
2fa10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2fa20 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
2fa30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2fa40 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2fa50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2fa60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2fa70 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2fa80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fa90 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2faa0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
2fab0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2fac0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2fad0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2fae0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2faf0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(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 69 6e 74  ol);.sqlite3_int
2fb20 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2fb30 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2fb40 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2fb50 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2fb60 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2fb70 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2fb80 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2fb90 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
2fba0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2fbb0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2fbc0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2fbd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2fbe0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
2fbf0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2fc00 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
2fc10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2fc20 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2fc30 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2fc40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fc50 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2fc60 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2fc70 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2fc80 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2fc90 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2fca0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2fcb0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2fcc0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2fcd0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2fce0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2fcf0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2fd00 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2fd10 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2fd20 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2fd30 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2fd40 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2fd50 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2fd60 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2fd70 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2fd80 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2fd90 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2fda0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2fdb0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2fdc0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2fdd0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2fde0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2fdf0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2fe00 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2fe10 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2fe20 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2fe30 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2fe40 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2fe50 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2fe60 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2fe70 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2fe80 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2fe90 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2fea0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2feb0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2fec0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2fed0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2fee0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2fef0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2ff00 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2ff10 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2ff20 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2ff30 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2ff40 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2ff50 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2ff60 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2ff70 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2ff80 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2ff90 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2ffa0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2ffb0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2ffc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2ffd0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2ffe0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2fff0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
30000 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
30010 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
30020 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
30030 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
30040 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
30050 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
30060 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
30070 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
30080 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
30090 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
300a0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
300b0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
300c0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
300d0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
300e0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
300f0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
30100 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
30110 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
30120 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
30130 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
30140 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
30150 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
30160 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30170 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
30180 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
30190 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
301a0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
301b0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
301c0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
301d0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
301e0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
301f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
30200 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
30210 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
30220 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
30230 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
30240 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
30250 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
30260 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
30270 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
30280 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
30290 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
302a0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
302b0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
302c0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
302d0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
302e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
302f0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
30300 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
30310 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
30320 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
30330 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
30340 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
30350 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
30360 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30370 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
30380 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
30390 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
303a0 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
303b0 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
303c0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
303d0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
303e0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
303f0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
30400 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
30410 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
30420 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
30430 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
30440 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
30450 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30460 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
30470 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
30480 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
30490 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
304a0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
304b0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
304c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
304d0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
304e0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
304f0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
30500 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
30510 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
30520 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
30530 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
30540 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
30550 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
30560 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
30570 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
30580 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
30590 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
305a0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
305b0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
305c0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
305d0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
305e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
305f0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
30600 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
30610 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
30620 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
30630 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
30640 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
30650 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
30660 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
30670 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
30680 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
30690 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
306a0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
306b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
306c0 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
306d0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
306e0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
306f0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
30700 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
30710 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
30720 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
30730 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
30740 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
30750 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
30760 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
30770 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
30780 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
30790 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
307a0 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
307b0 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
307c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
307d0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
307e0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
307f0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
30800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30810 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
30820 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
30830 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
30840 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
30850 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
30860 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
30870 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
30880 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
30890 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
308a0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
308b0 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
308c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
308d0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
308e0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
308f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
30900 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
30910 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30920 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
30930 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
30940 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
30950 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
30960 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
30970 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
30980 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
30990 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
309a0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
309b0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
309c0 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
309d0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
309e0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
309f0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
30a00 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
30a10 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
30a20 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
30a30 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
30a40 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
30a50 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
30a60 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
30a70 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
30a80 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
30a90 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
30aa0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
30ab0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
30ac0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
30ad0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
30ae0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
30af0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
30b00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
30b10 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
30b20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
30b30 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
30b40 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
30b50 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
30b60 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
30b70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
30b80 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
30b90 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
30ba0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
30bb0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
30bc0 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
30bd0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
30be0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
30bf0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
30c00 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
30c10 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
30c20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
30c30 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
30c40 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
30c50 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
30c60 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
30c70 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c  eters.  The appl
30c80 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73  ication should s
30c90 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  et this paramete
30ca0 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
30cb0 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20  UTF16LE] if the 
30cc0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
30cd0 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
30ce0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
30cf0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f  ue_text16le()] o
30d00 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b  n an input, or [
30d10 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20  SQLITE_UTF16BE] 
30d20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  if the.** implem
30d30 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
30d40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30d50 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61  text16be()] on a
30d60 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b  n input, or.** [
30d70 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66  SQLITE_UTF16] if
30d80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30d90 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65  text16()] is use
30da0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  d, or [SQLITE_UT
30db0 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  F8].** otherwise
30dc0 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c  .  ^The same SQL
30dd0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
30de0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
30df0 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67  iple times using
30e00 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72  .** different pr
30e10 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
30e20 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66  odings, with dif
30e30 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  ferent implement
30e40 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61  ations for.** ea
30e50 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20  ch encoding..** 
30e60 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
30e70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
30e80 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
30e90 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
30ea0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
30eb0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
30ec0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
30ed0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
30ee0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
30ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
30f00 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61  rth parameter ma
30f10 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
30f20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  ORed with [SQLIT
30f30 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
30f40 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68  .** to signal th
30f50 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  at the function 
30f60 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
30f70 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75  rn the same resu
30f80 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20  lt given.** the 
30f90 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68  same inputs with
30fa0 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  in a single SQL 
30fb0 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74  statement.  Most
30fc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
30fd0 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73  re.** determinis
30fe0 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d  tic.  The built-
30ff0 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51  in [random()] SQ
31000 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e  L function is an
31010 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a   example of a.**
31020 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69   function that i
31030 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73  s not determinis
31040 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65  tic.  The SQLite
31050 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69   query planner i
31060 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72  s able to.** per
31070 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20  form additional 
31080 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e  optimizations on
31090 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66   deterministic f
310a0 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65  unctions, so use
310b0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
310c0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
310d0 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d  ] flag is recomm
310e0 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73  ended where poss
310f0 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ible..**.** ^(Th
31100 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
31110 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
31120 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
31130 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31140 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
31150 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
31160 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
31170 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
31180 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
31190 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
311a0 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
311b0 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
311c0 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
311d0 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
311e0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
311f0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
31200 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
31210 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
31220 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
31230 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
31240 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
31250 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
31260 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
31270 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
31280 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
31290 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
312a0 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
312b0 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
312c0 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
312d0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
312e0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
312f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31300 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
31310 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
31320 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
31330 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
31340 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
31350 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
31360 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
31370 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
31380 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
31390 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
313a0 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
313b0 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
313c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
313d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
313e0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
313f0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
31400 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
31410 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
31420 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
31430 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
31440 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
31450 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
31460 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
31470 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
31480 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
31490 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
314a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
314b0 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
314c0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
314d0 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
314e0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
314f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31500 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
31510 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
31520 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
31530 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
31540 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
31550 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
31560 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
31570 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
31580 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
31590 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
315a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
315b0 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
315c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
315d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
315e0 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
315f0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
31600 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
31610 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
31620 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
31630 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
31640 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
31650 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
31660 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
31670 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
31680 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
31690 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
316a0 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
316b0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
316c0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
316d0 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
316e0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
316f0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
31700 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
31710 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
31720 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
31730 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
31740 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
31750 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
31760 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
31770 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
31780 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
31790 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
317a0 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
317b0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
317c0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
317d0 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
317e0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
317f0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
31800 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
31810 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
31820 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
31830 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
31840 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
31850 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
31860 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
31870 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
31880 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
31890 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
318a0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
318b0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
318c0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
318d0 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
318e0 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
318f0 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
31900 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
31910 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
31920 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31930 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
31940 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
31950 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31960 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
31970 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
31980 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
31990 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
319a0 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
319b0 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
319c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
319d0 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
319e0 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
319f0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
31a00 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
31a10 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
31a20 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
31a30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31a40 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
31a50 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
31a60 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
31a70 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
31a80 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
31a90 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
31aa0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
31ab0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
31ac0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31ad0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
31ae0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
31af0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
31b00 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
31b10 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
31b20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
31b30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
31b40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
31b50 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
31b60 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
31b70 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
31b80 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
31b90 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
31ba0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
31bb0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
31bc0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
31bd0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
31be0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
31bf0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
31c00 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31c10 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
31c20 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
31c30 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
31c40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31c50 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
31c60 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
31c70 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
31c80 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
31c90 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
31ca0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
31cb0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
31cc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31cd0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31ce0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
31cf0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
31d00 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
31d10 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
31d20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
31d30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31d40 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
31d50 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
31d60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31d70 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
31d80 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
31d90 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
31da0 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
31db0 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
31dc0 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
31dd0 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
31de0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
31df0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
31e00 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
31e10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
31e20 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
31e30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
31e40 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
31e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
31e60 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
31e70 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
31e80 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
31e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
31ea0 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
31eb0 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f  /* Deprecated */
31ec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31ed0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
31ee0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
31ef0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
31f00 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
31f10 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
31f20 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  n Flags.**.** Th
31f30 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ese constants ma
31f40 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68  y be ORed togeth
31f50 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  er with the .** 
31f60 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70  [SQLITE_UTF8 | p
31f70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
31f80 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66  coding] as the f
31f90 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
31fa0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
31fb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
31fc0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
31fd0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
31fe0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
31ff0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
32000 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  v2()]..*/.#defin
32010 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49  e SQLITE_DETERMI
32020 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a  NISTIC    0x800.
32030 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32040 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
32050 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
32060 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
32070 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
32080 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
32090 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
320a0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
320b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
320c0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
320d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
320e0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
320f0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
32100 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
32110 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
32120 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
32130 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
32140 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
32150 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
32160 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
32170 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
32180 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
32190 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
321a0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
321b0 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
321c0 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
321d0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
321e0 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
321f0 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
32200 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.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 65 78 70 69  int sqlite3_expi
32230 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
32240 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
32250 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
32260 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
32270 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
32280 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
32290 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
322a0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
322b0 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
322c0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
322d0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
322e0 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
322f0 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
32300 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
32310 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
32320 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
32330 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
32340 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20  64,int),.       
32350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
32360 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
32370 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
32380 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
32390 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
323a0 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
323b0 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
323c0 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
323d0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
323e0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
323f0 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
32400 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
32410 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
32420 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
32430 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
32440 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
32450 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
32460 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
32470 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
32480 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
32490 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
324a0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
324b0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
324c0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
324d0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
324e0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
324f0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
32500 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
32510 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
32520 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
32530 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
32540 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
32550 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
32560 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
32570 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
32580 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32590 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
325a0 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
325b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
325c0 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
325d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
325e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
325f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
32600 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
32610 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
32620 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
32630 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
32640 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32650 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
32660 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
32670 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
32680 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
32690 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
326a0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
326b0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
326c0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
326d0 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
326e0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
326f0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
32700 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
32710 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
32720 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
32730 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
32740 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
32750 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
32760 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
32770 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
32780 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32790 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
327a0 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
327b0 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
327c0 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
327d0 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
327e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
327f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32800 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
32810 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
32820 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
32830 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
32840 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
32850 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
32860 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
32870 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
32880 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32890 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
328a0 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
328b0 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
328c0 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
328d0 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
328e0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
328f0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
32900 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
32910 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
32920 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
32930 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
32940 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
32950 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
32960 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
32970 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
32980 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
32990 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
329a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
329b0 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
329c0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
329d0 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
329e0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
329f0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
32a00 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
32a10 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
32a20 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
32a30 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
32a40 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
32a50 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
32a60 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
32a70 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
32a80 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
32a90 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
32aa0 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
32ab0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
32ac0 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
32ad0 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
32ae0 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
32af0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
32b00 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
32b10 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
32b20 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
32b30 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
32b40 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
32b50 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
32b60 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
32b70 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
32b80 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
32b90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
32ba0 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
32bb0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
32bc0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
32bd0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
32be0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
32bf0 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
32c00 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
32c10 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
32c20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
32c30 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
32c40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
32c50 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
32c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
32c70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
32c80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32c90 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
32ca0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
32cb0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
32cc0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
32cd0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
32ce0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
32cf0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32d00 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
32d10 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
32d20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
32d30 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
32d40 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
32d50 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
32d60 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
32d70 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
32d80 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
32d90 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
32da0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32db0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32dc0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
32dd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32de0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
32df0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
32e00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32e10 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
32e20 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
32e30 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
32e40 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
32e50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
32e60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
32e70 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
32e80 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
32e90 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
32ea0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
32eb0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32ec0 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
32ed0 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
32ee0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
32ef0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
32f00 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
32f10 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
32f20 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
32f30 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
32f40 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
32f50 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
32f60 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
32f70 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
32f80 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
32f90 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
32fa0 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
32fb0 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
32fc0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
32fd0 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
32fe0 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
32ff0 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
33000 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
33010 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
33020 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
33030 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
33040 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
33050 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
33060 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33070 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
33080 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
33090 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
330a0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
330b0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
330c0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
330d0 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
330e0 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
330f0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
33100 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
33110 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
33120 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
33130 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
33140 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
33150 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
33160 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
33170 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
33180 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
33190 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
331a0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
331b0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
331c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
331d0 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
331e0 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
331f0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
33200 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
33210 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
33220 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33230 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
33240 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
33250 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
33260 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
33270 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33280 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33290 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
332a0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
332b0 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20  ointer .** when 
332c0 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20  first called if 
332d0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
332e0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
332f0 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a  or if a memory.*
33300 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72  * allocate error
33310 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e   occurs..**.** ^
33320 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73  (The amount of s
33330 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  pace allocated b
33340 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  y sqlite3_aggreg
33350 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
33360 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65   is.** determine
33370 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d  d by the N param
33380 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75  eter on first su
33390 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20  ccessful call.  
333a0 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20  Changing the.** 
333b0 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75  value of N in su
333c0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
333d0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
333e0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74  te_context() wit
333f0 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  hin.** the same 
33400 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
33410 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c  on instance will
33420 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20   not resize the 
33430 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
33440 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20  tion.)^  Within 
33450 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
33460 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f  ack, it is custo
33470 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e  mary to set.** N
33480 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73  =0 in calls to s
33490 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
334a0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f  _context(C,N) so
334b0 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69   that no .** poi
334c0 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c  ntless memory al
334d0 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e  locations occur.
334e0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
334f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
33500 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
33510 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
33520 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
33530 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
33540 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
33550 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
33560 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
33570 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
33580 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
33590 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
335a0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
335b0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
335c0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
335d0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
335e0 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
335f0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
33600 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
33610 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
33620 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
33630 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
33640 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
33650 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
33660 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
33670 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
33680 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
33690 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
336a0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
336b0 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
336c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
336d0 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
336e0 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
336f0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
33700 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
33710 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
33720 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
33730 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
33740 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
33750 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
33760 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
33770 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
33780 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
33790 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
337a0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
337b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
337c0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
337d0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
337e0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
337f0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
33800 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
33810 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
33820 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
33830 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
33840 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
33850 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
33860 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33870 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
33880 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
33890 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
338a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
338b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
338c0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
338d0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
338e0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
338f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
33900 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
33910 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
33920 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
33930 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
33940 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33950 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
33960 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
33970 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
33980 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
33990 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
339a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
339b0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
339c0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
339d0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
339e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
339f0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
33a00 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
33a10 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
33a20 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
33a30 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
33a40 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
33a50 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
33a60 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
33a70 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
33a80 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
33a90 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
33aa0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
33ab0 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
33ac0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
33ad0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
33ae0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
33af0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
33b00 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
33b10 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
33b20 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
33b30 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
33b40 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
33b50 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
33b60 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
33b70 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
33b80 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
33b90 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
33ba0 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
33bb0 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  n a regular-expr
33bc0 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a  ession matching.
33bd0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
33be0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
33bf0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
33c00 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
33c10 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  be stored as.** 
33c20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
33c30 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74  ted with the pat
33c40 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a  tern string.  .*
33c50 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61  * Then as long a
33c60 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  s the pattern st
33c70 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65  ring remains the
33c80 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f   same,.** the co
33c90 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
33ca0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
33cb0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
33cc0 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
33cd0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
33ce0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
33cf0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
33d00 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
33d10 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
33d20 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
33d30 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
33d40 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
33d50 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
33d60 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
33d70 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
33d80 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
33d90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33da0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
33db0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
33dc0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
33dd0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75  ated with the fu
33de0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c  nction argument,
33df0 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65   this sqlite3_ge
33e00 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
33e10 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
33e20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
33e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33e40 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
33e50 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61  C,N,P,X) interfa
33e60 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65  ce saves P as me
33e70 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
33e80 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
33e90 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33ea0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33eb0 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e  ion.  ^Subsequen
33ec0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
33ed0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
33ee0 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20  a(C,N) return P 
33ef0 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65  from the most re
33f00 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cent.** sqlite3_
33f10 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
33f20 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65  P,X) call if the
33f30 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69   metadata is sti
33f40 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e  ll valid or.** N
33f50 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64  ULL if the metad
33f60 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73  ata has been dis
33f70 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65  carded..** ^Afte
33f80 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73  r each call to s
33f90 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33fa0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72  ta(C,N,P,X) wher
33fb0 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  e X is not NULL,
33fc0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
33fd0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
33fe0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58  uctor function X
33ff0 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20   with parameter 
34000 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63  P exactly.** onc
34010 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61  e, when the meta
34020 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65  data is discarde
34030 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  d..** SQLite is 
34040 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20  free to discard 
34050 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20  the metadata at 
34060 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64  any time, includ
34070 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ing: <ul>.** <li
34080 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  > when the corre
34090 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
340a0 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
340b0 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ges, or.** <li> 
340c0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  when [sqlite3_re
340d0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
340e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
340f0 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  s called for the
34100 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61  .**      SQL sta
34110 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c  tement, or.** <l
34120 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f  i> when sqlite3_
34130 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73  set_auxdata() is
34140 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f   invoked again o
34150 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d  n the same param
34160 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  eter, or.** <li>
34170 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67   during the orig
34180 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74  inal sqlite3_set
34190 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20  _auxdata() call 
341a0 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a  when a memory .*
341b0 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f  *      allocatio
341c0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
341d0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  </ul>)^.**.** No
341e0 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c  te the last bull
341f0 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  et in particular
34200 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
34210 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74  r X in .** sqlit
34220 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
34230 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65  ,N,P,X) might be
34240 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74   called immediat
34250 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a  ely, before the.
34260 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
34270 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
34280 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e  ce even returns.
34290 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f    Hence sqlite3_
342a0 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a  set_auxdata().**
342b0 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65   should be calle
342c0 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f  d near the end o
342d0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
342e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  mplementation an
342f0 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  d the.** functio
34300 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
34310 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65   should not make
34320 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66   any use of P af
34330 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ter.** sqlite3_s
34340 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73  et_auxdata() has
34350 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a   been called..**
34360 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
34370 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
34380 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
34390 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
343a0 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  for.** function 
343b0 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
343c0 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  are compile-time
343d0 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c   constants, incl
343e0 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a  uding literal.**
343f0 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
34400 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70  ameters] and exp
34410 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65  ressions compose
34420 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e  d from the same.
34430 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
34440 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
34450 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
34460 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
34470 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
34480 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
34490 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
344a0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
344b0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
344c0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
344d0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
344e0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
344f0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
34500 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
34510 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
34520 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
34530 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
34540 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
34550 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
34560 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
34570 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
34580 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
34590 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
345a0 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
345b0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
345c0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
345d0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
345e0 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
345f0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
34600 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
34610 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
34620 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
34630 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
34640 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
34650 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
34660 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
34670 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
34680 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
34690 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
346a0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
346b0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
346c0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
346d0 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
346e0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
346f0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
34700 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
34710 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
34720 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
34730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
34740 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
34750 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
34760 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
34770 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
34780 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ers..*/.typedef 
34790 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
347a0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
347b0 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
347c0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
347d0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
347e0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
347f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
34800 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
34810 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
34820 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
34830 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
34840 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
34850 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a  An SQL Function.
34860 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
34870 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
34880 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
34890 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
348a0 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
348b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
348c0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
348d0 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
348e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
348f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34900 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
34910 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
34920 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
34930 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
34940 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
34950 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
34960 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
34970 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
34980 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
34990 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
349a0 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
349b0 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
349c0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
349d0 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
349e0 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
349f0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
34a00 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
34a10 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
34a20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34a30 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
34a40 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
34a50 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
34a60 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34a70 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
34a80 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
34a90 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
34aa0 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
34ab0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
34ac0 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
34ad0 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
34ae0 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
34af0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
34b00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34b10 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
34b20 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
34b30 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
34b40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34b50 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34b60 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
34b70 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
34b80 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
34b90 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
34ba0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
34bb0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
34bc0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
34bd0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34be0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
34bf0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
34c00 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
34c10 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
34c20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34c30 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
34c40 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
34c50 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
34c60 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
34c70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34c80 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
34c90 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
34ca0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
34cb0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
34cc0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
34cd0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
34ce0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
34cf0 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  tion..** ^SQLite
34d00 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
34d10 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
34d20 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
34d30 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
34d40 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
34d50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34d60 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
34d70 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
34d80 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e  rror message.  ^
34d90 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
34da0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
34db0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
34dc0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
34dd0 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
34de0 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69  -8. ^SQLite.** i
34df0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
34e00 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
34e10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
34e20 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
34e30 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
34e40 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74  rder.  ^If the t
34e50 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
34e60 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
34e70 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
34e80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34e90 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
34ea0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
34eb0 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
34ec0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
34ed0 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
34ee0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
34ef0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
34f00 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
34f10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
34f20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
34f30 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
34f40 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
34f50 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
34f60 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
34f70 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
34f80 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
34f90 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
34fa0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
34fb0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
34fc0 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  e..** ^The sqlit
34fd0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
34fe0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
34ff0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
35000 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
35010 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
35020 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
35030 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
35040 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
35050 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
35060 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
35070 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
35080 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
35090 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
350a0 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
350b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
350c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
350d0 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
350e0 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
350f0 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
35100 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
35110 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
35120 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
35130 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c  n.  ^By default,
35140 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
35150 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
35160 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65  OR.  ^A subseque
35170 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
35180 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35190 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
351a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
351b0 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
351c0 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
351d0 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _ERROR..**.** ^T
351e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
351f0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29  t_error_toobig()
35200 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
35210 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
35220 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
35230 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
35240 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
35250 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
35260 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
35270 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35280 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29  lt_error_nomem()
35290 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
352a0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
352b0 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
352c0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
352d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
352e0 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
352f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35300 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
35310 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
35320 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
35330 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35340 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35350 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
35360 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
35370 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
35380 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
35390 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ent..** ^The sql
353a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
353b0 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
353c0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
353d0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
353e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
353f0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35400 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
35410 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
35420 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
35430 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
35440 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35450 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
35460 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
35470 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
35480 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
35490 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
354a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
354b0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
354c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
354d0 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
354e0 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
354f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35500 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
35510 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35520 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
35530 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
35540 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
35550 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35560 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35570 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
35580 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
35590 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
355a0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
355b0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
355c0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
355d0 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
355e0 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
355f0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
35600 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
35610 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
35620 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
35630 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
35640 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
35650 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35660 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35670 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
35680 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
35690 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
356a0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
356b0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
356c0 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
356d0 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
356e0 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
356f0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
35700 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
35710 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
35720 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
35730 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35740 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35750 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
35760 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
35770 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
35780 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
35790 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
357a0 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
357b0 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
357c0 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
357d0 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
357e0 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
357f0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20  unction result. 
35800 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
35810 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67  meter is non-neg
35820 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a  ative, then it.*
35830 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  * must be the by
35840 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74  te offset into t
35850 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
35860 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
35870 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65  or would.** appe
35880 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ar if the string
35890 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69   where NUL termi
358a0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
358b0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
358c0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74  cur.** in the st
358d0 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f  ring at a byte o
358e0 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65  ffset that is le
358f0 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75  ss than the valu
35900 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20  e of the 3rd.** 
35910 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
35920 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
35930 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69  ring will contai
35940 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  n embedded NULs 
35950 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  and the.** resul
35960 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
35970 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74   operating on st
35980 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64  rings with embed
35990 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
359a0 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  fined..** ^If th
359b0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
359c0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
359d0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
359e0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
359f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
35a00 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
35a10 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
35a20 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
35a30 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
35a40 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
35a50 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
35a60 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
35a70 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
35a80 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
35a90 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
35aa0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
35ab0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35ac0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
35ad0 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
35ae0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
35af0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
35b00 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
35b10 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
35b20 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
35b30 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
35b40 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
35b50 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
35b60 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
35b70 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
35b80 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
35b90 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
35ba0 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
35bb0 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
35bc0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
35bd0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
35be0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
35bf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
35c00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35c10 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
35c20 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
35c30 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
35c40 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
35c50 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
35c60 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
35c70 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
35c80 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
35c90 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
35ca0 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
35cb0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
35cc0 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
35cd0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
35ce0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35cf0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
35d00 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
35d10 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
35d20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35d30 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
35d40 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
35d50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35d60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
35d70 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
35d80 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
35d90 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
35da0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
35db0 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
35dc0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
35dd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
35de0 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
35df0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
35e00 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
35e10 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
35e20 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
35e30 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
35e40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35e50 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
35e60 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
35e70 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
35e80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
35e90 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
35ea0 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
35eb0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
35ec0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
35ed0 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
35ee0 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
35ef0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
35f00 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
35f10 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
35f20 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
35f30 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
35f40 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
35f50 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
35f60 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
35f70 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
35f80 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
35f90 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35fa0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
35fb0 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
35fc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
35fd0 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
35fe0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
35ff0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
36000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36010 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
36020 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
36030 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
36040 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36050 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
36060 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
36070 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
36080 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36090 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
360a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
360b0 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
360c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
360d0 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
360e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
360f0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
36100 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36110 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
36120 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36130 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
36140 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
36150 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
36160 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
36170 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36180 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
36190 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
361a0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
361b0 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
361c0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
361d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
361e0 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
361f0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
36200 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
36210 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
36220 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
36230 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
36240 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
36250 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36260 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
36270 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
36280 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
36290 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
362a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
362b0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
362c0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
362d0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
362e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
362f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36300 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
36310 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
36320 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
36330 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
36340 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
36350 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
36360 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
36370 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
36380 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
36390 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
363a0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
363b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
363c0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
363d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
363e0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
363f0 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
36400 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
36410 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
36420 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
36430 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
36440 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
36450 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
36460 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
36470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36480 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
36490 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
364a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
364b0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
364c0 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
364d0 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
364e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
364f0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
36500 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36510 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
36520 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
36530 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
36540 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
36550 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36560 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
36570 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
36580 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
36590 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
365a0 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
365b0 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
365c0 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
365d0 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
365e0 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
365f0 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
36600 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
36610 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
36620 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
36630 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
36640 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
36650 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
36660 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
36670 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
36680 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
36690 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
366a0 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
366b0 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
366c0 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
366d0 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
366e0 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
366f0 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
36700 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
36710 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
36720 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
36730 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
36740 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
36750 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
36760 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
36770 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
36780 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
36790 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
367a0 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
367b0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
367c0 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
367d0 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
367e0 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
367f0 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
36800 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
36810 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
36820 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
36830 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
36840 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
36850 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  at is passed.** 
36860 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
36870 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
36880 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
36890 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
368a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
368b0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61  th argument, xCa
368c0 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69  llback, is a poi
368d0 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c  nter to the coll
368e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a  ating function..
368f0 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c  ** ^Multiple col
36900 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
36910 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
36920 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  ed using the sam
36930 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69  e name but.** wi
36940 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  th different eTe
36950 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73  xtRep parameters
36960 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c   and SQLite will
36970 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a   use whichever.*
36980 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  * function requi
36990 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
369a0 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61  ount of data tra
369b0 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20  nsformation..** 
369c0 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63  ^If the xCallbac
369d0 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  k argument is NU
369e0 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c  LL then the coll
369f0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
36a00 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e  s.** deleted.  ^
36a10 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  When all collati
36a20 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76  ng functions hav
36a30 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
36a40 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a  e are deleted,.*
36a50 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e  * that collation
36a60 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73   is no longer us
36a70 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
36a80 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36a90 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ion callback is 
36aa0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63  invoked with a c
36ab0 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20  opy of the pArg 
36ac0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
36ad0 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64  data pointer and
36ae0 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67   with two string
36af0 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  s in the encodin
36b00 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  g specified.** b
36b10 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61  y the eTextRep a
36b20 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f  rgument.  The co
36b30 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36b40 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a   must return an.
36b50 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  ** integer that 
36b60 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  is negative, zer
36b70 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a  o, or positive.*
36b80 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  * if the first s
36b90 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
36ba0 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  an, equal to, or
36bb0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
36bc0 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73  e second,.** res
36bd0 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f  pectively.  A co
36be0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36bf0 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74   must always ret
36c00 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73  urn the same ans
36c10 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65  wer.** given the
36c20 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49   same inputs.  I
36c30 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  f two or more co
36c40 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36c50 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
36c60 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
36c70 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28  collation name (
36c80 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20  using different 
36c90 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29  eTextRep values)
36ca0 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73   then all.** mus
36cb0 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61  t give an equiva
36cc0 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e  lent answer when
36cd0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71   invoked with eq
36ce0 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73  uivalent strings
36cf0 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69  ..** The collati
36d00 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
36d10 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77   obey the follow
36d20 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66  ing properties f
36d30 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67  or all.** string
36d40 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a  s A, B, and C:.*
36d50 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
36d60 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42  > If A==B then B
36d70 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==A..** <li> If 
36d80 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68  A==B and B==C th
36d90 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e  en A==C..** <li>
36da0 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20   If A&lt;B THEN 
36db0 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  B&gt;A..** <li> 
36dc0 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26  If A&lt;B and B&
36dd0 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43  lt;C then A&lt;C
36de0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
36df0 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20   If a collating 
36e00 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61  function fails a
36e10 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ny of the above 
36e20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
36e30 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e  that.** collatin
36e40 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72  g function is  r
36e50 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73  egistered and us
36e60 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
36e70 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
36e80 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
36e90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36ea0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36eb0 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
36ec0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
36ed0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
36ee0 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69  ** with the addi
36ef0 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44  tion that the xD
36f00 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
36f10 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41  is invoked on pA
36f20 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63  rg when.** the c
36f30 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36f40 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  n is deleted..**
36f50 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63   ^Collating func
36f60 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65  tions are delete
36f70 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
36f80 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
36f90 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ter.** calls to 
36fa0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  the collation cr
36fb0 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
36fc0 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20   or when the.** 
36fd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36fe0 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20  tion] is closed 
36ff0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
37000 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  lose()]..**.** ^
37010 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  The xDestroy cal
37020 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c  lback is <u>not<
37030 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68  /u> called if th
37040 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  e .** sqlite3_cr
37050 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37060 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  2() function fai
37070 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ls.  Application
37080 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a  s that invoke.**
37090 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
370a0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
370b0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78  ith a non-NULL x
370c0 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74  Destroy argument
370d0 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63   should .** chec
370e0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
370f0 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66  e and dispose of
37100 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37110 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   data pointer.**
37120 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68   themselves rath
37130 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e  er than expectin
37140 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c  g SQLite to deal
37150 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65   with it for the
37160 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69  m..** This is di
37170 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65  fferent from eve
37180 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ry other SQLite 
37190 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
371a0 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a  inconsistency .*
371b0 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65  * is unfortunate
371c0 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63   but cannot be c
371d0 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62  hanged without b
371e0 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64  reaking backward
371f0 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  s .** compatibil
37200 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ity..**.** See a
37210 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
37220 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37230 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
37240 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37250 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
37260 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37270 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
37280 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
37290 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
372a0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
372b0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
372c0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
372d0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
372e0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
372f0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
37300 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37310 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
37320 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
37330 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
37340 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
37350 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
37360 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
37370 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
37380 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
37390 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
373a0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
373b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
373c0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
373d0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
373e0 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
373f0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
37400 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
37410 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
37420 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37430 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37440 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
37450 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
37460 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
37470 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
37480 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
37490 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
374a0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
374b0 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
374c0 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
374d0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
374e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
374f0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
37500 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
37510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37520 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
37530 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
37540 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
37550 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
37560 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
37570 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
37580 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
37590 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
375a0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
375b0 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
375c0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
375d0 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
375e0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
375f0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
37600 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
37610 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
37620 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37630 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
37640 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
37650 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
37660 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
37670 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
37680 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
37690 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
376a0 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
376b0 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
376c0 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
376d0 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
376e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
376f0 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
37700 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
37710 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
37720 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
37730 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
37740 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37750 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
37760 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37770 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
37780 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
37790 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
377a0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
377b0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
377c0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
377d0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
377e0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
377f0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
37800 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
37810 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
37820 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
37830 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
37840 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
37850 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
37860 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
37870 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
37880 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
37890 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
378a0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
378b0 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
378c0 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
378d0 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
378e0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
378f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37900 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
37910 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37920 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
37930 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37940 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
37950 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
37960 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
37970 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
37980 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
37990 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
379a0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
379b0 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
379c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
379d0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
379e0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
379f0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
37a00 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
37a10 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
37a20 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
37a30 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
37a40 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
37a50 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
37a60 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
37a70 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
37a80 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
37a90 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
37aa0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
37ab0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
37ac0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
37ad0 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
37ae0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
37af0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
37b00 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
37b10 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
37b20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
37b30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37b40 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
37b50 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
37b60 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
37b70 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
37b80 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69   The key */.);.i
37b90 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76  nt sqlite3_key_v
37ba0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
37bb0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
37bc0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
37bd0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
37be0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37bf0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
37c00 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
37c10 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
37c20 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
37c30 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
37c40 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
37c50 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
37c60 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
37c70 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
37c80 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
37c90 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
37ca0 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
37cb0 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
37cc0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
37cd0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
37ce0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
37cf0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
37d00 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
37d10 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
37d20 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
37d30 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
37d40 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
37d50 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
37d60 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
37d70 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
37d80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
37d90 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
37da0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
37db0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
37dc0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
37dd0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
37de0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
37df0 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  y_v2(.  sqlite3 
37e00 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
37e10 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
37e20 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
37e30 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
37e40 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
37e50 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
37e60 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  the database */.
37e70 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
37e80 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
37e90 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
37ea0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
37eb0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
37ec0 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
37ed0 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
37ee0 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
37ef0 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
37f00 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
37f10 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
37f20 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
37f30 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
37f40 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
37f50 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
37f60 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
37f70 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
37f80 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
37f90 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
37fa0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
37fb0 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
37fc0 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
37fd0 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
37fe0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
37ff0 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
38000 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
38010 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
38020 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
38030 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
38040 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
38050 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
38060 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
38070 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
38080 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
38090 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
380a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
380b0 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
380c0 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
380d0 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
380e0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
380f0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
38100 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
38110 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
38120 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
38130 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
38140 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
38150 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
38160 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
38170 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
38180 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
38190 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
381a0 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
381b0 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
381c0 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
381d0 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
381e0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
381f0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
38200 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
38210 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
38220 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
38230 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
38240 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
38250 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
38260 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
38270 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
38280 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
38290 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
382a0 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
382b0 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
382c0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
382d0 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
382e0 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
382f0 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
38300 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
38310 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
38320 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
38330 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
38340 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
38350 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
38360 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
38370 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
38380 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
38390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
383a0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
383b0 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
383c0 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
383d0 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
383e0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
383f0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
38400 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
38410 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
38420 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
38430 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
38440 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
38450 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
38460 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
38470 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
38480 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
38490 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
384a0 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
384b0 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
384c0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
384d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
384e0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
384f0 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
38500 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
38510 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
38520 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
38530 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
38540 69 6f 6e 73 20 61 72 65 20 73 74 72 6f 6e 67 6c  ions are strongl
38550 79 20 64 69 73 63 6f 75 72 61 67 65 64 20 66 72  y discouraged fr
38560 6f 6d 20 75 73 69 6e 67 20 74 68 69 73 20 67 6c  om using this gl
38570 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 2e 0a 2a  obal variable..*
38580 2a 20 49 74 20 69 73 20 72 65 71 75 69 72 65 64  * It is required
38590 20 74 6f 20 73 65 74 20 61 20 74 65 6d 70 6f 72   to set a tempor
385a0 61 72 79 20 66 6f 6c 64 65 72 20 6f 6e 20 57 69  ary folder on Wi
385b0 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 28 57  ndows Runtime (W
385c0 69 6e 52 54 29 2e 0a 2a 2a 20 42 75 74 20 66 6f  inRT)..** But fo
385d0 72 20 61 6c 6c 20 6f 74 68 65 72 20 70 6c 61 74  r all other plat
385e0 66 6f 72 6d 73 2c 20 69 74 20 69 73 20 68 69 67  forms, it is hig
385f0 68 6c 79 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  hly recommended 
38600 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
38610 73 0a 2a 2a 20 6e 65 69 74 68 65 72 20 72 65 61  s.** neither rea
38620 64 20 6e 6f 72 20 77 72 69 74 65 20 74 68 69 73  d nor write this
38630 20 76 61 72 69 61 62 6c 65 2e 20 20 54 68 69 73   variable.  This
38640 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
38650 20 69 73 20 61 20 72 65 6c 69 63 0a 2a 2a 20 74   is a relic.** t
38660 68 61 74 20 65 78 69 73 74 73 20 66 6f 72 20 62  hat exists for b
38670 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
38680 62 69 6c 69 74 79 20 6f 66 20 6c 65 67 61 63 79  bility of legacy
38690 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
386a0 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  d should.** be a
386b0 76 6f 69 64 65 64 20 69 6e 20 6e 65 77 20 70 72  voided in new pr
386c0 6f 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 49 74  ojects..**.** It
386d0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
386e0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
386f0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
38700 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
38710 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
38720 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
38730 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
38740 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
38750 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
38760 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38770 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
38780 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
38790 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
387a0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
387b0 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
387c0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
387d0 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
387e0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
387f0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
38800 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51