/ Hex Artifact Content
Login

Artifact b04790da19184e883da788d07688f16230d2cb6b:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4a60: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4a70: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4a80: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4a90: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4aa0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4ab0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4ac0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4ad0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4ae0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4af0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4b00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4b10: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4b20: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4b30: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4b40: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4b50: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a   error codes}.**
4b60: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b70: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b80: 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  } {extended resu
4b90: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4ba0: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4bb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4bc0: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4bd0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4be0: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
4bf0: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
4c00: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4c10: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4c20: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4c30: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4c40: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4c50: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4c60: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4c70: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
4c80: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4c90: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4ca0: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4cb0: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4cc0: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4cd0: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4ce0: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4cf0: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4d00: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4d10: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4d20: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
4d30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
4d40: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
4d50: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
4d60: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
4d70: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
4d80: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4d90: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
4da0: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
4db0: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
4dc0: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
4dd0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
4de0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
4df0: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
4e00: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
4e10: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78  the available ex
4e20: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4e30: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68  des are listed h
4e40: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20  ere..** One may 
4e50: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65  expect the numbe
4e60: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65  r of extended re
4e70: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20  sult codes will 
4e80: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65  be expand.** ove
4e90: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72  r time.  Softwar
4ea0: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65  e that uses exte
4eb0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4ec0: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a  s should expect.
4ed0: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65  ** to see new re
4ee0: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75  sult codes in fu
4ef0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
4f00: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
4f10: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73  he SQLITE_OK res
4f20: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65  ult code will ne
4f30: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e  ver be extended.
4f40: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73    It will always
4f50: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a  .** be exactly z
4f60: 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ero..*/.#define 
4f70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4f80: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4f90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4fa0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4fb0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4fc0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4fd0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4fe0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4ff0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
5000: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5010: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
5020: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5080: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
51e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51f0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
5200: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5210: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
5220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5230: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5240: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5250: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5270: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5280: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5290: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
52a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52b0: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
52c0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
52d0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
52e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52f0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
5300: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5310: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
5320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5330: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
5340: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5350: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
53a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53b0: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
53c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53d0: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
53e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53f0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
5400: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5410: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
5420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5430: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
5440: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5450: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5470: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5480: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5490: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
54a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54b0: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
54c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54d0: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
54e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54f0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
5500: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5510: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
5520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5530: 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20  ERR_MMAP        
5540: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5550: 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23  ERR | (24<<8)).#
5560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5570: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5580: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5590: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
55a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
55b0: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
55c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
55d0: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
55e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5600: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5610: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5620: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5630: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5640: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5650: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5660: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5680: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5690: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
56a0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
56b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
56c0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56d0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56e0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56f0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5700: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5710: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5720: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5740: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5750: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5760: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5780: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5790: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
57a0: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
57b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
57c0: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  RT_ROLLBACK     
57d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f       (SQLITE_ABO
57e0: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RT | (2<<8)).#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5800: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20  TRAINT_CHECK    
5810: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5820: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29  TRAINT | (1<<8))
5830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5840: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49  CONSTRAINT_COMMI
5850: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f  THOOK   (SQLITE_
5860: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c  CONSTRAINT | (2<
5870: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5880: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5890: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c  OREIGNKEY   (SQL
58a0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
58b0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
58d0: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  NT_FUNCTION     
58e0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
58f0: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  NT | (4<<8)).#de
5900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5910: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20  TRAINT_NOTNULL  
5920: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5930: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29  TRAINT | (5<<8))
5940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5950: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41  CONSTRAINT_PRIMA
5960: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  RYKEY   (SQLITE_
5970: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c  CONSTRAINT | (6<
5980: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54  ITE_CONSTRAINT_T
59a0: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c  RIGGER      (SQL
59b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
59c0: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
59d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59e0: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20  NT_UNIQUE       
59f0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5a00: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  NT | (8<<8)).#de
5a10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a20: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20  TRAINT_VTAB     
5a30: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5a40: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29  TRAINT | (9<<8))
5a50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5a60: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5a70: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5a80: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5a90: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5aa0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5ab0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5ac0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5ad0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5ae0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5af0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5b00: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5b10: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5b20: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5b30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5b40: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5b50: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5b60: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5b70: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5b80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5b90: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
5ba0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
5bb0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5bc0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5be0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5bf0: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5c00: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5c10: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5c20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c30: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5c40: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5c50: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5c60: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c70: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5c80: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
5c90: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5cb0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
5cc0: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
5cd0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5cf0: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
5d00: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
5d10: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5d20: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5d30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d40: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
5d50: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
5d60: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5d70: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d90: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
5da0: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
5db0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5dd0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
5de0: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
5df0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e10: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
5e20: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
5e30: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e50: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
5e60: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
5e70: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e90: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
5ea0: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
5eb0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ec0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ed0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
5ee0: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
5ef0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f10: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
5f20: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
5f30: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f50: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
5f60: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
5f70: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f80: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fa0: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
5fb0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
5fc0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5fd0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ff0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
6000: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
6010: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6020: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6030: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6040: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
6050: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
6060: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6070: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6080: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6090: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
60a0: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
60b0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
60c0: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
60d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
60e0: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
60f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6100: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
6110: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
6120: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6130: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
6140: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
6150: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
6160: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
6170: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
6180: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
6190: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
61a0: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
61b0: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
61c0: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
61d0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
61e0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
61f0: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
6200: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6210: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
6220: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6230: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6240: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6250: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
6260: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
6270: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6280: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
6290: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
62a0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
62b0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
62c0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
62d0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
62e0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
62f0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6300: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6310: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6320: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6330: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6340: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
6350: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
6360: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
6370: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
6380: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
6390: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
63a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
63b0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
63c0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
63d0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
63e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63f0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6400: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6410: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6420: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6430: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6440: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
6450: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
6460: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6470: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6480: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
6490: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
64a0: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
64b0: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
64c0: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
64d0: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
64e0: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
64f0: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
6500: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
6510: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
6520: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
6530: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
6540: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
6550: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
6560: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
6570: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
6580: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6590: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
65a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
65b0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
65c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
65d0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
65e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
65f0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6600: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6610: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6620: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6630: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6640: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6650: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6670: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6680: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6690: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
66a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
66b0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
66c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
66d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
66e0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
66f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6700: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6710: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6720: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6730: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6750: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6760: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6770: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6780: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6790: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
67a0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
67b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
67c0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
67d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
67e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
67f0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6800: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6810: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6820: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6830: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6840: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6850: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6860: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
6870: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6880: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6890: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
68a0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
68b0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
68c0: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
68d0: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
68e0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
68f0: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
6900: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6910: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
6920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6930: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
6940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6950: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
6960: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6970: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6980: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6990: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
69a0: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
69b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
69c0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
69d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
69e0: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
69f0: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
6a00: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
6a10: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
6a20: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
6a30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6a40: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
6a50: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
6a60: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
6a70: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6a80: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
6a90: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
6aa0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
6ab0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
6ac0: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
6ad0: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
6ae0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
6af0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
6b00: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
6b10: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
6b20: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
6b30: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
6b40: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
6b50: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
6b60: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
6b70: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6b80: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
6b90: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6ba0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
6bb0: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
6bc0: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
6bd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6be0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
6bf0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
6c00: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6c10: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6c20: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
6c30: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
6c40: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6c50: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6c60: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
6c70: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
6c80: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
6c90: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
6ca0: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
6cb0: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
6cc0: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
6cd0: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
6ce0: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
6cf0: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
6d00: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
6d10: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
6d20: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
6d30: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
6d40: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6d50: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
6d60: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
6d70: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
6d80: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
6d90: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
6da0: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
6db0: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
6dc0: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
6dd0: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
6de0: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
6df0: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
6e00: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
6e10: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
6e20: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
6e30: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
6e40: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
6e50: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e60: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
6e70: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
6e80: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
6e90: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
6ea0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
6eb0: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
6ec0: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
6ed0: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
6ee0: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
6ef0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6f00: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
6f10: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6f20: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
6f30: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
6f40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6f50: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
6f60: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
6f70: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6f80: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
6f90: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
6fa0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6fb0: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6fc0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
6fd0: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
6fe0: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
6ff0: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
7000: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
7010: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
7020: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
7030: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
7040: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
7050: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
7060: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
7070: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
7080: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
7090: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
70a0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
70b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
70c0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
70d0: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
70e0: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
70f0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
7100: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
7110: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7120: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
7130: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
7140: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7150: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
7160: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7170: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
7180: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
7190: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
71a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
71b0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
71c0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
71d0: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
71e0: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
71f0: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
7200: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7210: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
7220: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
7230: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
7240: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
7250: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
7260: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7270: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
7280: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7290: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
72a0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
72b0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
72c0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
72d0: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
72e0: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
72f0: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
7300: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
7310: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
7320: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7330: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
7340: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7350: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
7360: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7370: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7380: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
7390: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
73a0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
73b0: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
73c0: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
73d0: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
73e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
73f0: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
7400: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
7410: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
7420: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
7430: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7440: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
7450: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
7460: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
7470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7480: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
7490: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
74a0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
74b0: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
74c0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
74d0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
74e0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
74f0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7500: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
7510: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
7520: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
7530: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
7540: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
7550: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
7560: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7570: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
7580: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7590: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
75a0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
75b0: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
75c0: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
75d0: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
75e0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
75f0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
7600: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
7610: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
7620: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
7630: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
7640: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7650: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
7660: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7670: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
7680: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7690: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
76a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
76b0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
76c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
76d0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
76e0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
76f0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
7700: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
7710: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
7720: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
7730: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7740: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
7750: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
7760: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7770: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7780: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7790: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
77a0: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
77b0: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
77c0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
77d0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
77e0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
77f0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
7800: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
7810: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
7820: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
7830: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7840: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
7850: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
7860: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
7870: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7880: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7890: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
78a0: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
78b0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
78c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
78d0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
78e0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
78f0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
7900: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
7910: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
7920: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
7930: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
7940: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
7950: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
7960: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
7970: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7980: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7990: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
79a0: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
79b0: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
79c0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
79d0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
79e0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
79f0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
7a00: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
7a10: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
7a20: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
7a30: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
7a40: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
7a50: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
7a60: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
7a70: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
7a80: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
7a90: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
7aa0: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
7ab0: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
7ac0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
7ad0: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
7ae0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7af0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
7b00: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
7b10: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
7b20: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
7b30: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
7b40: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
7b50: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
7b60: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
7b70: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
7b80: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
7b90: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
7ba0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
7bb0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
7bc0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
7bd0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
7be0: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
7bf0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
7c00: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
7c10: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
7c20: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
7c30: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
7c40: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
7c50: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
7c60: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
7c70: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
7c80: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7c90: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7ca0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
7cb0: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
7cc0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
7cd0: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
7ce0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
7cf0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
7d00: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
7d10: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
7d20: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
7d30: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
7d40: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
7d50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7d60: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
7d70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7d80: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
7d90: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7da0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
7db0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7dc0: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
7dd0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7de0: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
7df0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e00: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
7e10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e20: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
7e30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7e40: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
7e50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7e60: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
7e70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7e80: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7e90: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
7ea0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7eb0: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
7ec0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
7ed0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
7ee0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
7ef0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
7f00: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
7f10: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7f20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
7f30: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
7f40: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
7f50: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
7f60: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
7f70: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
7f80: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
7f90: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
7fa0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
7fb0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
7fc0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7fd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
7fe0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
7ff0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
8000: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
8010: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
8020: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
8030: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
8040: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
8050: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
8060: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
8070: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
8080: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8090: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
80a0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
80b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
80c0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
80d0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
80e0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
80f0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
8100: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
8110: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
8120: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
8130: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
8140: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
8150: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
8160: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
8170: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
8180: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
8190: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
81a0: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
81b0: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
81c0: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
81d0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
81e0: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
81f0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
8200: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
8210: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8220: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8230: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
8240: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
8250: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
8260: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
8270: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
8280: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
8290: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
82a0: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
82b0: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
82c0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
82d0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
82e0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
82f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
8300: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8310: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8320: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8330: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
8340: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8350: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
8360: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
8370: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8380: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
8390: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
83a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
83b0: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
83c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
83d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
83e0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
83f0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
8400: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8410: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
8420: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
8430: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
8440: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
8450: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
8460: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8470: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
8480: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
8490: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
84a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
84b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
84c0: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
84d0: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
84e0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
84f0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
8500: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
8510: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
8520: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
8530: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
8540: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
8550: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
8560: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8570: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
8580: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
8590: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
85a0: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
85b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
85c0: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
85d0: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
85e0: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
85f0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8600: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
8610: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74   */.  int (*xFet
8620: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8630: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8640: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74   iOfst, int iAmt
8650: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20  , void **pp);.  
8660: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28  int (*xUnfetch)(
8670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8680: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8690: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20  st, void *p);.  
86a0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
86b0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
86c0: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a  ersion 3 */.  /*
86d0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
86e0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
86f0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
8700: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
8710: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
8720: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
8730: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
8740: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8750: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8760: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8770: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8780: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8790: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
87a0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
87b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
87c0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
87d0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
87e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
87f0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8800: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8810: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8820: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8830: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8840: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8850: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8860: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8870: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8880: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8890: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
88a0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
88b0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
88c0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
88d0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
88e0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
88f0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8900: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8910: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8920: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8930: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8940: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8950: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8960: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8970: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8980: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8990: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
89a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
89b0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
89c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
89d0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
89e0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
89f0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8a00: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8a10: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8a20: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8a30: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8a40: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8a50: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8a60: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8a70: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8a80: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8a90: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8aa0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8ab0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8ac0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8ad0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8ae0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8af0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8b00: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8b10: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8b20: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8b30: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8b40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8b50: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8b60: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8b70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8b80: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8b90: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
8ba0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
8bb0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
8bc0: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
8bd0: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
8be0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
8bf0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8c00: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8c10: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8c20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8c30: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8c40: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
8c50: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
8c60: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
8c70: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
8c80: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
8c90: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
8ca0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
8cb0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
8cc0: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
8cd0: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
8ce0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
8cf0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
8d00: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
8d10: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
8d20: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
8d30: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
8d40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8d50: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
8d60: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
8d70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
8d80: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
8d90: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
8da0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
8db0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
8dc0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
8dd0: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
8de0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
8df0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
8e00: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
8e10: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8e20: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
8e30: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
8e40: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
8e50: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8e60: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
8e70: 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65  ITTED]].** ^(The
8e80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8e90: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
8ea0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
8eb0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
8ec0: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
8ed0: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
8ee0: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
8ef0: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
8f00: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
8f10: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
8f20: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
8f30: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
8f40: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
8f50: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
8f60: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
8f70: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
8f80: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
8f90: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
8fa0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
8fb0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
8fc0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
8fd0: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
8fe0: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
8ff0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
9000: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
9010: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9020: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
9030: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9040: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
9050: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9060: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
9070: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9080: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9090: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
90a0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
90b0: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
90c0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
90d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
90e0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
90f0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9100: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9110: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9120: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9130: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9140: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9150: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9160: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9170: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9180: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9190: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
91a0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
91b0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
91c0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
91d0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
91e0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
91f0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9200: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9210: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9220: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9230: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9240: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9250: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9260: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9270: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9280: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9290: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
92a0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
92b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
92c0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
92d0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
92e0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
92f0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9300: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9310: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9320: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9330: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9340: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9350: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9360: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9370: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9380: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9390: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
93a0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
93b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
93c0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
93d0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
93e0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
93f0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9400: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9410: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9420: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9430: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9440: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9450: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9460: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9470: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9480: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9490: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
94a0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
94b0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
94c0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
94d0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
94e0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
94f0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9500: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9510: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9520: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9530: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9540: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9550: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9560: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9570: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9580: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9590: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
95a0: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
95b0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
95c0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
95d0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
95e0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
95f0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9600: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9610: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9620: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9630: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9640: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9650: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9660: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9670: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9680: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9690: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
96a0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
96b0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
96c0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
96d0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
96e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
96f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9700: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9710: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9720: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9730: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9740: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9750: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9760: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9770: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9780: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9790: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
97a0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
97b0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
97c0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
97d0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
97e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
97f0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9800: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9810: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9820: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9830: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9840: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9850: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9860: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9870: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9880: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9890: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
98a0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
98b0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
98c0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
98d0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
98e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
98f0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9900: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9910: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9920: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9930: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9940: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9950: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9960: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9970: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9980: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9990: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
99a0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
99b0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
99c0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
99d0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
99e0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
99f0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9a00: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9a10: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
9a20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9a30: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
9a40: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
9a50: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
9a60: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
9a70: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
9a80: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
9a90: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9aa0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
9ab0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
9ac0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9ad0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9ae0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9af0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9b00: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
9b10: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
9b20: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b30: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
9b40: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
9b50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9b60: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9b70: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
9b80: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
9b90: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
9ba0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
9bb0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
9bc0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
9bd0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
9be0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
9bf0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9c00: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
9c10: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
9c20: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
9c30: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
9c40: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
9c50: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
9c60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9c70: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
9c80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9c90: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
9ca0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
9cb0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
9cc0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
9cd0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
9ce0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
9cf0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
9d00: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
9d10: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
9d20: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
9d30: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
9d40: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
9d50: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
9d60: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
9d70: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
9d80: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
9d90: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
9da0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
9db0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
9dc0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
9dd0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
9de0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
9df0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
9e00: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
9e10: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
9e20: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
9e30: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
9e40: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
9e50: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
9e60: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
9e70: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
9e80: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
9e90: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
9ea0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
9eb0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
9ec0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
9ed0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
9ee0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
9ef0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
9f00: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
9f10: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
9f20: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
9f30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9f40: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
9f50: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
9f60: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
9f70: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
9f80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
9f90: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9fa0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
9fb0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
9fc0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
9fd0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
9fe0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
9ff0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a000: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a010: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a020: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a030: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a040: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a050: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a060: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a070: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a080: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a090: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a0a0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a0b0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a0c0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a0d0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a0e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a0f0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a100: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a110: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a120: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a130: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a140: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a150: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a160: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a170: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a180: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a190: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a1a0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a1b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a1c0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a1d0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a1e0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a1f0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a200: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a210: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a220: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a230: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a240: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a250: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a260: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a270: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a280: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a290: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a2a0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a2b0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a2c0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a2d0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a2e0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a2f0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a300: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a310: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a320: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a330: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a340: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a350: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a360: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a370: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a380: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a390: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a3a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a3b0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a3c0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a3d0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a3e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a3f0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a400: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a410: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
a420: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
a430: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
a440: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
a450: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
a460: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
a470: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
a480: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a490: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a4a0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
a4b0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
a4c0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
a4d0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
a4e0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
a4f0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
a500: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
a510: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
a520: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a530: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
a540: 5d 5d 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65  ]].** ^This file
a550: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
a560: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
a570: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
a580: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
a590: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
a5a0: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
a5b0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
a5c0: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
a5d0: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
a5e0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
a5f0: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
a600: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
a610: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
a620: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
a630: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
a640: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
a650: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
a660: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
a670: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
a680: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
a690: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
a6a0: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
a6b0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
a6c0: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
a6d0: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
a6e0: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
a6f0: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
a700: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
a710: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
a720: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
a730: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
a740: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
a750: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
a760: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
a770: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
a780: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
a790: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
a7a0: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
a7b0: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
a7c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a7d0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
a7e0: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
a7f0: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
a800: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a810: 6c 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  l to have SQLite
a820: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
a830: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
a840: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
a850: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
a860: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
a870: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
a880: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
a890: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
a8a0: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
a8b0: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
a8c0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
a8d0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
a8e0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
a8f0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
a900: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
a910: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a920: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a930: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
a940: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
a950: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
a960: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
a970: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
a980: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
a990: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a9a0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
a9b0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 61 72 67 75  ZE]].** The argu
a9c0: 6d 65 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20  ment is assumed 
a9d0: 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  to point to a va
a9e0: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
a9f0: 74 65 33 5f 69 6e 74 36 34 2e 20 41 6e 0a 2a 2a  te3_int64. An.**
aa00: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
aa10: 6d 20 61 6d 6f 75 6e 74 20 6f 66 20 74 68 69 73  m amount of this
aa20: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
aa30: 6d 61 70 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a  map in bytes..**
aa40: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
aa50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
aa60: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
aa70: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
aa80: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
aa90: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
aaa0: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
aab0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
aac0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
aad0: 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
aae0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
aaf0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
ab00: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
ab10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
ab20: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
ab30: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
ab40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
ab50: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
ab60: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
ab70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
ab80: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
ab90: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
aba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
abb0: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
abc0: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
abd0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
abe0: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
abf0: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
ac00: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
ac10: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
ac20: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
ac30: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
ac40: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
ac50: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
ac60: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
ac70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
ac80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ac90: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
aca0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
acb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
acc0: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
acd0: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
ace0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
acf0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
ad00: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
ad10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ad20: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
ad30: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
ad40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ad50: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
ad60: 20 20 20 20 20 20 20 20 20 31 38 0a 0a 2f 2a 0a           18../*.
ad70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
ad80: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
ad90: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
ada0: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
adb0: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
adc0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
add0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
ade0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
adf0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
ae00: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
ae10: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
ae20: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
ae30: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
ae40: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
ae50: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
ae60: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
ae70: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
ae80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
ae90: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
aea0: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
aeb0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
aec0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
aed0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
aee0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
aef0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
af00: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
af10: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
af20: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
af30: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
af40: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
af50: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
af60: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
af70: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
af80: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
af90: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
afa0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
afb0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
afc0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
afd0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
afe0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
aff0: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
b000: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
b010: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
b020: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
b030: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
b040: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
b050: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
b060: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
b070: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
b080: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
b090: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
b0a0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
b0b0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
b0c0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
b0d0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
b0e0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
b0f0: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
b100: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
b110: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
b120: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
b130: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
b140: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
b150: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
b160: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
b170: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
b180: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
b190: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
b1a0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
b1b0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
b1c0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
b1d0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
b1e0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
b1f0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
b200: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
b210: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
b220: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
b230: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
b240: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
b250: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
b260: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
b270: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
b280: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
b290: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
b2a0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
b2b0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
b2c0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
b2d0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
b2e0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
b2f0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
b300: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
b310: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
b320: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
b330: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
b340: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
b350: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
b360: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
b370: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
b380: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
b390: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
b3a0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
b3b0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
b3c0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
b3d0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
b3e0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
b3f0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
b400: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
b410: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
b420: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
b430: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
b440: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
b450: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
b460: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
b470: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
b480: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
b490: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
b4a0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
b4b0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
b4c0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
b4d0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
b4e0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
b4f0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
b500: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
b510: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
b520: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
b530: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
b540: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
b550: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
b560: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
b570: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
b580: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
b590: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
b5a0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
b5b0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
b5c0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
b5d0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
b5e0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
b5f0: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
b600: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
b610: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
b620: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
b630: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
b640: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
b650: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
b660: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
b670: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
b680: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
b690: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
b6a0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
b6b0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
b6c0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
b6d0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
b6e0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
b6f0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
b700: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
b710: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
b720: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
b730: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
b740: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
b750: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
b760: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
b770: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
b780: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
b790: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
b7a0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
b7b0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
b7c0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
b7d0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
b7e0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
b7f0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
b800: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
b810: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
b820: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
b830: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
b840: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
b850: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
b860: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
b870: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
b880: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
b890: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
b8a0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
b8b0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
b8c0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
b8d0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
b8e0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
b8f0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
b900: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
b910: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
b920: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
b930: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
b940: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
b950: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
b960: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
b970: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
b980: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
b990: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
b9a0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
b9b0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
b9c0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
b9d0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
b9e0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
b9f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ba00: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
ba10: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
ba20: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
ba30: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
ba40: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ba50: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
ba60: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ba70: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
ba80: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
ba90: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
baa0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
bab0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
bac0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
bad0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
bae0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
baf0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
bb00: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
bb10: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
bb20: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
bb30: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
bb40: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
bb50: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
bb60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
bb70: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
bb80: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
bb90: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
bba0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
bbb0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
bbc0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
bbd0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
bbe0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
bbf0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
bc00: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
bc10: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
bc20: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
bc30: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
bc40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
bc50: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
bc60: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
bc70: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
bc80: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
bc90: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
bca0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
bcb0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
bcc0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
bcd0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
bce0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
bcf0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
bd00: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
bd10: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
bd20: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
bd30: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
bd40: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
bd50: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
bd60: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
bd70: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
bd80: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
bd90: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
bda0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
bdb0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
bdc0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
bdd0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
bde0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
bdf0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
be00: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
be10: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
be20: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
be30: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be40: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
be50: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
be60: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
be70: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
be80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
be90: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
bea0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
beb0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
bec0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
bed0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
bee0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
bef0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
bf00: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
bf10: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
bf20: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
bf30: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
bf40: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
bf50: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
bf60: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
bf70: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
bf80: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
bf90: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
bfa0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
bfb0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
bfc0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
bfd0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
bfe0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
bff0: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
c000: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
c010: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
c020: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
c030: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
c040: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
c050: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
c060: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
c070: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
c080: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
c090: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
c0a0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
c0b0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
c0c0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
c0d0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
c0e0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
c0f0: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
c100: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
c110: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
c120: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
c130: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
c140: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
c150: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
c160: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
c170: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
c180: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
c190: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
c1a0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
c1b0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
c1c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
c1d0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
c1e0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
c1f0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
c200: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
c210: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
c220: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
c230: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
c240: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
c250: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
c260: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
c270: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
c280: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
c290: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
c2a0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
c2b0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
c2c0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
c2d0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
c2e0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
c2f0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
c300: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
c310: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
c320: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
c330: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
c340: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
c350: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
c360: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
c370: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
c380: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
c390: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
c3a0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
c3b0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
c3c0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
c3d0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
c3e0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
c3f0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
c400: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
c410: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
c420: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
c430: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
c440: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
c450: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
c460: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
c470: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
c480: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
c490: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
c4a0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
c4b0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
c4c0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
c4d0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
c4e0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
c4f0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
c500: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
c510: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
c520: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
c530: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
c540: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
c550: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
c560: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
c570: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
c580: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
c590: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
c5a0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
c5b0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
c5c0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
c5d0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
c5e0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
c5f0: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
c600: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
c610: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
c620: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
c630: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
c640: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
c650: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
c660: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
c670: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
c680: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
c690: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
c6a0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
c6b0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
c6c0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
c6d0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
c6e0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
c6f0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
c700: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
c710: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
c720: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
c730: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
c740: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
c750: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
c760: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
c770: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
c780: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
c790: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
c7a0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
c7b0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
c7c0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
c7d0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
c7e0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
c7f0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
c800: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
c810: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
c820: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
c830: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
c840: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
c850: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
c860: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
c870: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
c880: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
c890: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
c8a0: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
c8b0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
c8c0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
c8d0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
c8e0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
c8f0: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
c900: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
c910: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
c920: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
c930: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
c940: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
c950: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
c960: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
c970: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
c980: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
c990: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
c9a0: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
c9b0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
c9c0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
c9d0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
c9e0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
c9f0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
ca00: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
ca10: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
ca20: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
ca30: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
ca40: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
ca50: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
ca60: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
ca70: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
ca80: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
ca90: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
caa0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
cab0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
cac0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
cad0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
cae0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
caf0: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
cb00: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
cb10: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
cb20: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
cb30: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
cb40: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
cb50: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
cb60: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
cb70: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
cb80: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
cb90: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
cba0: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
cbb0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
cbc0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
cbd0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
cbe0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
cbf0: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
cc00: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
cc10: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
cc20: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
cc30: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
cc40: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
cc50: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
cc60: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
cc70: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
cc80: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
cc90: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
cca0: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
ccb0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
ccc0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
ccd0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
cce0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
ccf0: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
cd00: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
cd10: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
cd20: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
cd30: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
cd40: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
cd50: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
cd60: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
cd70: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
cd80: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
cd90: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
cda0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
cdb0: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
cdc0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
cdd0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
cde0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
cdf0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
ce00: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
ce10: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
ce20: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
ce30: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
ce40: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
ce50: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
ce60: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
ce70: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
ce80: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
ce90: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
cea0: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
ceb0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
cec0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
ced0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
cee0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
cef0: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
cf00: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
cf10: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
cf20: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
cf30: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
cf40: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
cf50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
cf60: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
cf70: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
cf80: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
cf90: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
cfa0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
cfb0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
cfc0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
cfd0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
cfe0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
cff0: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
d000: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
d010: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
d020: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
d030: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
d040: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
d050: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
d060: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
d070: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
d080: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
d090: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d0a0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d0b0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
d0c0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
d0d0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
d0e0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
d0f0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
d100: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
d110: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
d120: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
d130: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
d140: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
d150: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
d160: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
d170: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
d180: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
d190: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
d1a0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
d1b0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
d1c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
d1d0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
d1e0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
d1f0: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
d200: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
d210: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
d220: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
d230: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
d240: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
d250: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
d260: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
d270: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
d280: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
d290: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
d2a0: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
d2b0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
d2c0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
d2d0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
d2e0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
d2f0: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
d300: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
d310: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d320: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
d330: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
d340: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
d350: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
d360: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
d370: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
d380: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
d390: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
d3a0: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
d3b0: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
d3c0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
d3d0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
d3e0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
d3f0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
d400: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
d410: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
d420: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
d430: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
d440: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
d450: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
d460: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
d470: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
d480: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
d490: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
d4a0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
d4b0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
d4c0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
d4d0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
d4e0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
d4f0: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
d500: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
d510: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
d520: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
d530: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
d540: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
d550: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
d560: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
d570: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d580: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
d590: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
d5a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
d5b0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
d5c0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
d5d0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
d5e0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
d5f0: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
d600: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
d610: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
d620: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
d630: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
d640: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
d650: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
d660: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
d670: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
d680: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
d690: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
d6a0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
d6b0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
d6c0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
d6d0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
d6e0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
d6f0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
d700: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
d710: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
d720: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
d730: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
d740: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
d750: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
d760: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
d770: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
d780: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
d790: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
d7a0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
d7b0: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
d7c0: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
d7d0: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
d7e0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
d7f0: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
d800: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
d810: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
d820: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
d830: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
d840: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
d850: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
d860: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
d870: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
d880: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
d890: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
d8a0: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
d8b0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
d8c0: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
d8d0: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
d8e0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
d8f0: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
d900: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d910: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
d920: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
d930: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
d940: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
d950: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
d960: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
d970: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d980: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
d990: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
d9a0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
d9b0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
d9c0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
d9d0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
d9e0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
d9f0: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
da00: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
da10: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
da20: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
da30: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
da40: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
da50: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
da60: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
da70: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
da80: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
da90: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
daa0: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
dab0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
dac0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
dad0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
dae0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
daf0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
db00: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
db10: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
db20: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
db30: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
db40: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
db50: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
db60: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
db70: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
db80: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
db90: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
dba0: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
dbb0: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
dbc0: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
dbd0: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
dbe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
dbf0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
dc00: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
dc10: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
dc20: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
dc30: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
dc40: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
dc50: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
dc60: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
dc70: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
dc80: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
dc90: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
dca0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
dcb0: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
dcc0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
dcd0: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
dce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
dcf0: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
dd00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
dd10: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
dd20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
dd30: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
dd40: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
dd50: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
dd60: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
dd70: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
dd80: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
dd90: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
dda0: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
ddb0: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
ddc0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
ddd0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
dde0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
ddf0: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
de00: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
de10: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
de20: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
de30: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
de40: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
de50: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
de60: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
de70: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
de80: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
de90: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
dea0: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
deb0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
dec0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
ded0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
dee0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
def0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
df00: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
df10: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
df20: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
df30: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
df40: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
df50: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
df60: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
df70: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
df80: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
df90: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
dfa0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
dfb0: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
dfc0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
dfd0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
dfe0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
dff0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
e000: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
e010: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
e020: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
e030: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
e040: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
e050: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e060: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
e070: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
e080: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
e090: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
e0a0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
e0b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e0c0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
e0d0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
e0e0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
e0f0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
e100: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
e110: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
e120: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
e130: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
e140: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
e150: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
e160: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
e170: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
e180: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e190: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
e1a0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
e1b0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
e1c0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
e1d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
e1e0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
e1f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e200: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
e210: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
e220: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e230: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
e240: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
e250: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
e260: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
e270: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
e280: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
e290: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
e2a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e2b0: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
e2c0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
e2d0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
e2e0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
e2f0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
e300: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
e310: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
e320: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
e330: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
e340: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
e350: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
e360: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
e370: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
e380: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
e390: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
e3a0: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
e3b0: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
e3c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
e3d0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
e3e0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
e3f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
e400: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
e410: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
e420: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
e430: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
e440: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
e450: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
e460: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
e470: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e480: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
e490: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
e4a0: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
e4b0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
e4c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e4d0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
e4e0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
e4f0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
e500: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
e510: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
e520: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
e530: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
e540: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
e550: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
e560: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
e570: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
e580: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
e590: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
e5a0: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
e5b0: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
e5c0: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
e5d0: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
e5e0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
e5f0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
e600: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
e610: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e620: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
e630: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
e640: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
e650: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
e660: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
e670: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
e680: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
e690: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
e6a0: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
e6b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
e6c0: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
e6d0: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
e6e0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
e6f0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
e700: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
e710: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
e720: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
e730: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
e740: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
e750: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
e760: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
e770: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
e780: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
e790: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
e7a0: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
e7b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
e7c0: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
e7d0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
e7e0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
e7f0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
e800: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
e810: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
e820: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
e830: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
e840: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
e850: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
e860: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
e870: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
e880: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
e890: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
e8a0: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
e8b0: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
e8c0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
e8d0: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
e8e0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
e8f0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
e900: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
e910: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
e920: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
e930: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
e940: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
e950: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
e960: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
e970: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
e980: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
e990: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
e9a0: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
e9b0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
e9c0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
e9d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
e9e0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
e9f0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
ea00: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
ea10: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
ea20: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
ea30: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
ea40: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
ea50: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
ea60: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
ea70: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
ea80: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
ea90: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
eaa0: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
eab0: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
eac0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
ead0: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
eae0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
eaf0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
eb00: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
eb10: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
eb20: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
eb30: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
eb40: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
eb50: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
eb60: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
eb70: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
eb80: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
eb90: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
eba0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
ebb0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
ebc0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
ebd0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
ebe0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
ebf0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
ec00: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
ec10: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ec20: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
ec30: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
ec40: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
ec50: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
ec60: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
ec70: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
ec80: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
ec90: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
eca0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
ecb0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
ecc0: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
ecd0: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
ece0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
ecf0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
ed00: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
ed10: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
ed20: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
ed30: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
ed40: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
ed50: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
ed60: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
ed70: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
ed80: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
ed90: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
eda0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
edb0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
edc0: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
edd0: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
ede0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
edf0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
ee00: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
ee10: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
ee20: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
ee30: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
ee40: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
ee50: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
ee60: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
ee70: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
ee80: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
ee90: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
eea0: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
eeb0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
eec0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
eed0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
eee0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
eef0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
ef00: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
ef10: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
ef20: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
ef30: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
ef40: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
ef50: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
ef60: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
ef70: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
ef80: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
ef90: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
efa0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
efb0: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
efc0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
efd0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
efe0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
eff0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
f000: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
f010: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
f020: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
f030: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
f040: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
f050: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
f060: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
f070: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f080: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
f090: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
f0a0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
f0b0: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
f0c0: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
f0d0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
f0e0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
f0f0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
f100: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
f110: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
f120: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
f130: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f140: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
f150: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
f160: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
f170: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
f180: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
f190: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
f1a0: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
f1b0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f1c0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
f1d0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
f1e0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
f1f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f200: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
f210: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
f220: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
f230: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
f240: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
f250: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
f260: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f270: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
f280: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
f290: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f2a0: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
f2b0: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
f2c0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
f2d0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
f2e0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
f2f0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
f300: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
f310: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f320: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
f330: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
f340: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
f350: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
f360: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
f370: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
f380: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
f390: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
f3a0: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
f3b0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
f3c0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
f3d0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
f3e0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
f3f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f400: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
f410: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
f420: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
f430: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
f440: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
f450: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
f460: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
f470: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
f480: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
f490: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
f4a0: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
f4b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f4c0: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
f4d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
f4e0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
f4f0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
f500: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
f510: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
f520: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
f530: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
f540: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
f550: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
f560: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
f570: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
f580: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
f590: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
f5a0: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
f5b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f5c0: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
f5d0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
f5e0: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
f5f0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
f600: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
f610: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
f620: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
f630: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
f640: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
f650: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
f660: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
f670: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
f680: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
f690: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f6a0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
f6b0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
f6c0: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
f6d0: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
f6e0: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
f6f0: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
f700: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
f710: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
f720: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
f730: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
f740: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
f750: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
f760: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  essful..*/.int s
f770: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f780: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
f790: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
f7a0: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
f7b0: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
f7c0: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
f7d0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
f7e0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
f7f0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
f800: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
f810: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
f820: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
f830: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
f840: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
f850: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
f860: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
f870: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
f880: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
f890: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
f8a0: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
f8b0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
f8c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f8d0: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
f8e0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
f8f0: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
f900: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
f910: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
f920: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
f930: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
f940: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
f950: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
f960: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
f970: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
f980: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
f990: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
f9a0: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
f9b0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
f9c0: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
f9d0: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
f9e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
f9f0: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
fa00: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
fa10: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
fa20: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
fa30: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
fa40: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
fa50: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
fa60: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
fa70: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
fa80: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
fa90: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
faa0: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
fab0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
fac0: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
fad0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
fae0: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
faf0: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
fb00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
fb10: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
fb20: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
fb30: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
fb40: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
fb50: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
fb60: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
fb70: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
fb80: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
fb90: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
fba0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
fbb0: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
fbc0: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
fbd0: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
fbe0: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
fbf0: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
fc00: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
fc10: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
fc20: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
fc30: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
fc40: 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46  xRealloc, and xF
fc50: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
fc60: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
fc70: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  * malloc(), real
fc80: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
fc90: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
fca0: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
fcb0: 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  ibrary..** ^SQLi
fcc0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
fcd0: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
fce0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
fcf0: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
fd00: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
fd10: 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
fd20: 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
fd30: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
fd40: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
fd50: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
fd60: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fd70: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
fd80: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
fd90: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
fda0: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
fdb0: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
fdc0: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
fdd0: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
fde0: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
fdf0: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
fe00: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
fe10: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
fe20: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
fe30: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
fe40: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
fe50: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
fe60: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
fe70: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
fe80: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
fe90: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
fea0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
feb0: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
fec0: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
fed0: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
fee0: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
fef0: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
ff00: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
ff10: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
ff20: 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
ff30: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
ff40: 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
ff50: 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
ff60: 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
ff70: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
ff80: 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
ff90: 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
ffa0: 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
ffb0: 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
ffc0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
ffd0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ffe0: 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
fff0: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
10000 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
10010 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
10020 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
10030 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
10040 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
10050 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
10060 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
10070 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
10080 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
10090 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
100a0 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
100b0 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
100c0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
100d0 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
100e0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
100f0 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
10100 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
10110 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
10120 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
10130 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
10140 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
10150 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
10160 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
10170 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
10180 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
10190 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
101a0 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
101b0 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
101c0 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
101d0 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
101e0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
101f0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
10200 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
10210 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10220 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
10230 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
10240 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
10250 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
10260 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
10270 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
10280 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
10290 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
102a0 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
102b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
102c0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
102d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
102e0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
102f0 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
10300 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
10310 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
10320 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
10330 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
10340 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
10350 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
10360 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
10370 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
10380 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
10390 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
103a0 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
103b0 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
103c0 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
103d0 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
103e0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
103f0 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
10400 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
10410 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
10420 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
10430 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
10440 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
10450 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
10460 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
10470 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
10480 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
10490 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
104a0 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
104b0 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
104c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
104d0 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
104e0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
104f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
10500 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
10510 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
10520 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
10530 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
10540 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
10550 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
10560 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
10570 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
10580 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
10590 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
105a0 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
105b0 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
105c0 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
105d0 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
105e0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
105f0 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
10600 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
10610 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
10620 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
10630 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
10640 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
10650 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
10660 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
10670 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
10680 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
10690 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
106a0 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
106b0 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
106c0 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
106d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
106e0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
106f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
10700 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10710 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
10720 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
10730 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
10740 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
10750 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
10760 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
10770 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
10780 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
10790 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
107a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
107b0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
107c0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
107d0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
107e0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
107f0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
10800 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
10810 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
10820 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
10830 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
10840 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
10850 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
10860 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
10870 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
10880 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
10890 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
108a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
108b0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
108c0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
108d0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
108e0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
108f0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
10900 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
10910 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
10920 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
10930 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
10940 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
10950 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
10960 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
10970 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
10980 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
10990 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
109a0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
109b0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
109c0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
109d0 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
109e0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
109f0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
10a00 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
10a10 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
10a20 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
10a30 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
10a40 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
10a50 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
10a60 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
10a70 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
10a80 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
10a90 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
10aa0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
10ab0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
10ac0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
10ad0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
10ae0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
10af0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
10b00 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
10b10 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
10b20 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
10b30 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10b40 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
10b50 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
10b60 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
10b70 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
10b80 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
10b90 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
10ba0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
10bb0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10bc0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
10bd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10be0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
10bf0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
10c00 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
10c10 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
10c20 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
10c30 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
10c40 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
10c50 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
10c60 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
10c70 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
10c80 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
10c90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10ca0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
10cb0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
10cc0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
10cd0 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
10ce0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
10cf0 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
10d00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10d10 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
10d20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
10d30 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
10d40 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
10d50 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
10d60 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
10d70 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
10d80 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
10d90 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
10da0 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
10db0 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
10dc0 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
10dd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10de0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
10df0 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
10e00 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10e10 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10e20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10e30 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
10e40 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
10e50 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10e60 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
10e70 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
10e80 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
10e90 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
10ea0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
10eb0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
10ec0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
10ed0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
10ee0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
10ef0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
10f00 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
10f10 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
10f20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10f30 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
10f40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10f50 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
10f60 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
10f70 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
10f80 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
10f90 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
10fa0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
10fb0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
10fc0 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
10fd0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
10fe0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
10ff0 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
11000 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
11010 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
11020 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
11030 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
11040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11050 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
11060 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
11070 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
11080 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
11090 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
110a0 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
110b0 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
110c0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
110d0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
110e0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
110f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11100 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
11110 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
11120 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
11130 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
11140 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
11150 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
11160 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
11170 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
11180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
11190 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
111a0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
111b0 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
111c0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
111d0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
111e0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
111f0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11200 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11210 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11220 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
11230 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
11240 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
11250 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
11260 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11270 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
11280 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
11290 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
112a0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
112b0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
112c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
112d0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
112e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
112f0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
11300 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11310 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11320 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11330 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11340 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11350 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11360 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
11370 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
11380 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
11390 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
113a0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
113b0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
113c0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
113d0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
113e0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
113f0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
11400 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11410 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
11420 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
11430 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
11440 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
11450 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
11460 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
11470 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
11480 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
11490 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
114a0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
114b0 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
114c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
114d0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
114e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
114f0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
11500 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11510 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11520 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11530 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11540 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
11550 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
11560 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
11570 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
11580 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11590 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
115a0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
115b0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
115c0 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
115d0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
115e0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
115f0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
11600 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
11610 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
11620 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
11630 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
11640 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
11650 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
11660 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
11670 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
11680 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
11690 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
116a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
116b0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
116c0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
116d0 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
116e0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
116f0 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
11700 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
11710 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
11720 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
11730 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
11740 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
11750 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
11760 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
11770 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
11780 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
11790 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
117a0 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
117b0 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
117c0 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
117d0 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
117e0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
117f0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
11800 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
11810 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
11820 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
11830 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
11840 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
11850 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
11860 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
11870 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
11880 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
11890 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
118a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
118b0 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
118c0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
118d0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
118e0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
118f0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
11900 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
11910 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
11920 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
11930 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11940 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
11950 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
11960 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11970 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
11980 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11990 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
119a0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
119b0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
119c0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
119d0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
119e0 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
119f0 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
11a00 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
11a10 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
11a20 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
11a30 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
11a40 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
11a50 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
11a60 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
11a70 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
11a80 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
11a90 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
11aa0 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
11ab0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
11ac0 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
11ad0 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
11ae0 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
11af0 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
11b00 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68  ple of 16..** Th
11b10 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11b20 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
11b30 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
11b40 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
11b50 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
11b60 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
11b70 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
11b80 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
11b90 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68  than two scratch
11ba0 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
11bb0 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
11bc0 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
11bd0 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65  wice the expecte
11be0 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
11bf0 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20   of threads..** 
11c00 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
11c10 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72  er require a scr
11c20 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
11c30 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
11c40 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
11c50 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
11c60 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
11c70 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
11c80 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
11c90 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
11ca0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
11cb0 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
11cc0 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
11cd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
11ce0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
11cf0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
11d00 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
11d10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
11d30 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
11d40 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
11d50 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
11d60 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
11d70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
11d80 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
11d90 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
11da0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
11db0 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
11dc0 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
11dd0 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
11de0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
11df0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
11e00 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
11e10 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
11e20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
11e30 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
11e40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
11e50 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
11e60 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
11e70 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e  _PCACHE2 option.
11e80 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
11e90 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
11ea0 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
11eb0 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
11ec0 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
11ed0 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
11ee0 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
11ef0 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
11f00 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
11f10 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
11f20 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
11f30 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
11f40 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
11f50 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
11f60 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
11f70 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
11f80 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
11f90 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
11fa0 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
11fb0 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
11fc0 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
11fd0 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
11fe0 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
11ff0 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
12000 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
12010 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
12020 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
12030 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
12040 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
12050 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
12060 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
12070 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
12080 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
12090 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
120a0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
120b0 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
120c0 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
120d0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
120e0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
120f0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
12100 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
12110 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
12120 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
12130 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
12140 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
12150 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
12160 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
12170 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
12180 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
12190 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
121a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
121b0 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
121c0 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
121d0 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
121e0 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
121f0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
12200 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
12210 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
12220 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
12230 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
12240 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
12250 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
12260 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12270 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
12280 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
12290 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
122a0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
122b0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
122c0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
122d0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
122e0 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
122f0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
12300 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
12310 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
12320 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
12330 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
12340 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
12350 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12360 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
12370 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12380 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
12390 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
123a0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
123b0 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
123c0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
123d0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
123e0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
123f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
12400 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
12410 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
12420 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
12430 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
12440 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
12450 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
12460 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
12470 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
12480 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
12490 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
124a0 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
124b0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
124c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
124d0 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
124e0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
124f0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
12500 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
12510 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
12520 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
12530 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
12540 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
12550 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
12560 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
12570 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
12580 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
12590 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
125a0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
125b0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
125c0 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
125d0 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
125e0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
125f0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
12600 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
12610 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
12620 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
12630 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
12640 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
12650 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
12660 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
12670 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
12680 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
12690 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
126a0 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
126b0 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
126c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
126d0 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
126e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
126f0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
12700 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12710 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12720 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12730 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
12740 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12750 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
12760 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12770 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
12780 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
12790 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
127a0 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
127b0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
127c0 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
127d0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
127e0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
127f0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
12800 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
12810 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  ** content of th
12820 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
12830 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12840 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
12850 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
12860 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
12870 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
12880 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12890 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
128a0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
128b0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
128c0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
128d0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
128e0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
128f0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
12900 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
12910 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
12920 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
12930 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12940 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
12950 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
12960 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12970 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
12980 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
12990 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
129a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
129b0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
129c0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
129d0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
129e0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
129f0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12a00 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12a10 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
12a20 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12a30 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
12a40 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12a50 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
12a60 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12a70 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
12a80 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
12a90 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
12aa0 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
12ab0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
12ac0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
12ad0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
12ae0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
12af0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
12b00 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
12b10 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
12b20 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
12b30 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
12b40 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
12b50 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
12b60 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
12b70 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12b80 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12b90 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12ba0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12bb0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
12bc0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
12bd0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
12be0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
12bf0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
12c00 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
12c10 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
12c20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12c30 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
12c40 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
12c50 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
12c60 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
12c70 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12c80 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
12c90 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12ca0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
12cb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12cc0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
12cd0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
12ce0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
12cf0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
12d00 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
12d10 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
12d20 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
12d30 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
12d40 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
12d50 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
12d60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
12d70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12d80 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
12d90 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
12da0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
12db0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
12dc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
12dd0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
12de0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
12df0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
12e00 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
12e10 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
12e20 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
12e30 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
12e40 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
12e50 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
12e60 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
12e70 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
12e80 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
12e90 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
12ea0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12eb0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
12ec0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
12ed0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12ee0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12ef0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
12f00 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
12f10 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
12f20 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
12f30 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12f40 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
12f50 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
12f60 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
12f70 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
12f80 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
12f90 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
12fa0 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
12fb0 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
12fc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
12fd0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
12fe0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
12ff0 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
13000 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
13010 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13020 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
13030 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13040 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
13050 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13060 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
13070 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
13080 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13090 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
130a0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
130b0 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
130c0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
130d0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
130e0 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
130f0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
13100 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
13110 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
13120 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
13130 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13140 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
13150 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
13160 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
13170 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13180 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
13190 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
131a0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
131b0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
131c0 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
131d0 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
131e0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
131f0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
13200 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
13210 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
13220 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
13230 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
13240 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
13250 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
13260 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
13270 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
13280 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
13290 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
132a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
132b0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
132c0 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
132d0 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
132e0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
132f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13300 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
13310 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
13320 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
13330 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
13340 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
13350 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
13360 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
13370 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
13380 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
13390 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
133a0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
133b0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
133c0 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
133d0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
133e0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
133f0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
13400 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
13410 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
13420 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
13430 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
13440 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
13450 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
13460 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
13470 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
13480 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
13490 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
134a0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
134b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
134c0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
134d0 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
134e0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
134f0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
13500 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
13510 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
13520 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
13530 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
13540 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
13550 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
13560 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
13570 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
13580 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
13590 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
135a0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
135b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
135c0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
135d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
135e0 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54  IG_URI.** <dd> T
135f0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13600 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13610 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20  nt of type int. 
13620 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
13630 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e  n.** URI handlin
13640 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
13650 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
13660 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
13670 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
13680 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c  ng.** is globall
13690 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55  y disabled. If U
136a0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
136b0 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
136c0 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
136d0 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
136e0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
136f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
13700 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
13710 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
13720 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
13730 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
13740 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
13750 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
13760 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
13770 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
13780 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
13790 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
137a0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
137b0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
137c0 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69   opened. If it i
137d0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
137e0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
137f0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
13800 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
13810 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
13820 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
13830 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
13840 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13850 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20  n is opened. By 
13860 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
13870 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
13880 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
13890 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
138a0 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
138b0 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
138c0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
138d0 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
138e0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
138f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13900 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
13910 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
13920 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
13930 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
13940 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  dd> This option 
13950 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
13960 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20  nteger argument 
13970 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
13980 65 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f  eted as.** a boo
13990 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
139a0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
139b0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
139c0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
139d0 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65  or.** full table
139e0 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
139f0 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20  ery optimizer.  
13a00 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
13a10 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
13a20 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
13a30 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
13a40 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
13a50 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13a60 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
13a70 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
13a80 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
13a90 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
13aa0 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
13ab0 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
13ac0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
13ad0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
13ae0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
13af0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
13b00 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
13b10 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
13b20 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
13b30 2a 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77  ** malfunction w
13b40 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
13b50 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
13b60 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
13b70 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
13b80 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
13b90 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
13ba0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
13bb0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
13bc0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
13bd0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
13be0 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
13bf0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
13c00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13c10 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
13c20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13c30 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
13c40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13c50 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
13c60 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
13c70 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
13c80 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
13c90 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
13ca0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
13cb0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
13cc0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
13cd0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
13ce0 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
13cf0 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
13d00 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dl>.**.** [[SQ
13d10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
13d20 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
13d30 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
13d40 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
13d50 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
13d60 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
13d70 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13d80 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45   the.** SQLITE_E
13d90 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 20 70 72 65  NABLE_SQLLOG pre
13da0 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
13db0 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
13dc0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
13dd0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
13de0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
13df0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
13e00 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
13e10 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
13e20 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
13e30 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
13e40 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
13e50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
13e60 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
13e70 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
13e80 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
13e90 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
13ea0 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
13eb0 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
13ec0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
13ed0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
13ee0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
13ef0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
13f00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
13f10 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
13f20 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
13f30 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
13f40 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
13f50 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
13f60 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
13f70 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
13f80 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
13f90 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
13fa0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
13fb0 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
13fc0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
13fd0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
13fe0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
13ff0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
14000 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
14010 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
14020 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
14030 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
14040 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
14050 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
14060 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14070 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
14080 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
14090 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
140a0 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
140b0 63 61 73 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  case..** </dl>.*
140c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
140d0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
140e0 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
140f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14100 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
14110 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
14120 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14130 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
14140 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
14150 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
14160 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14170 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
14180 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
14190 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
141a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
141b0 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
141c0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
141d0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
141e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
141f0 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
14200 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
14210 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
14220 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14230 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
14240 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
14250 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
14260 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14270 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
14280 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
14290 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
142a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
142b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
142c0 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
142d0 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
142e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
142f0 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
14300 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
14310 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
14320 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14330 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
14340 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
14350 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
14360 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
14370 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
14380 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
14390 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
143a0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
143b0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
143c0 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
143d0 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
143e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
143f0 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
14400 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
14410 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14420 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
14430 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
14440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14450 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
14460 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
14470 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
14480 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
14490 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
144a0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
144b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
144c0 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
144d0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
144e0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
144f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14500 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14510 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
14520 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14530 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
14540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14550 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
14560 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
14570 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14580 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
14590 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
145a0 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   void* */../*.**
145b0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
145c0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
145d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
145e0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
145f0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
14600 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
14610 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
14620 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
14630 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
14640 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
14650 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
14660 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14670 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
14680 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
14690 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
146a0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
146b0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
146c0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
146d0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
146e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
146f0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
14700 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
14710 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
14720 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
14730 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
14740 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
14750 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
14760 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
14770 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
14780 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
14790 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
147a0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
147b0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
147c0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
147d0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
147e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
147f0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
14800 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
14810 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
14820 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14830 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
14840 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
14850 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
14860 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
14870 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
14880 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
14890 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
148a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
148b0 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
148c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
148d0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
148e0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
148f0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
14900 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
14910 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
14920 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
14930 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
14940 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
14950 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
14960 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
14970 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
14980 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
14990 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
149a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
149b0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
149c0 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
149d0 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
149e0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
149f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
14a00 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
14a10 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
14a20 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
14a30 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
14a40 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
14a50 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
14a60 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
14a70 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
14a80 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
14a90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
14aa0 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
14ab0 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
14ac0 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
14ad0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
14ae0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
14af0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
14b00 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
14b10 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
14b20 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
14b30 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14b40 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
14b50 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
14b60 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
14b70 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
14b80 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
14b90 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
14ba0 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
14bb0 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
14bc0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
14bd0 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
14be0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
14bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
14c00 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
14c10 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
14c20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
14c30 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
14c40 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
14c50 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
14c60 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
14c70 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
14c80 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
14c90 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
14ca0 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
14cb0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
14cc0 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
14cd0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
14ce0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
14cf0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
14d00 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
14d10 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
14d20 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
14d30 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
14d40 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
14d50 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
14d60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
14d70 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
14d80 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
14d90 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
14da0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
14db0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
14dc0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
14dd0 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
14de0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
14df0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
14e00 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
14e10 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
14e20 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
14e30 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
14e40 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
14e50 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
14e60 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
14e70 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
14e80 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
14e90 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
14ea0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
14eb0 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
14ec0 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
14ed0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
14ee0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
14ef0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
14f00 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
14f10 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
14f20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
14f30 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
14f40 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
14f50 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
14f60 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
14f70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14f80 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
14f90 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
14fa0 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
14fb0 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
14fc0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
14fd0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
14fe0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
14ff0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
15000 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
15010 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
15020 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
15030 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
15040 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
15050 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
15060 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
15070 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
15080 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
15090 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
150a0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
150b0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
150c0 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
150d0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
150e0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
150f0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
15100 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
15110 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
15120 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15130 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15140 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
15150 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
15160 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
15170 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
15180 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
15190 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
151a0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
151b0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
151c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
151d0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
151e0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
151f0 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
15200 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
15210 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
15220 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
15230 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
15240 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15250 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
15260 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
15270 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
15280 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
15290 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
152a0 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
152b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
152c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
152d0 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
152e0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
152f0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
15300 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
15310 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
15320 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
15330 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
15340 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
15350 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
15360 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
15370 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
15380 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
15390 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
153a0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
153b0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
153c0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
153d0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
153e0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
153f0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
15400 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
15410 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
15420 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
15430 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15440 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
15450 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  Rowid.**.** ^Eac
15460 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
15470 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
15480 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
15490 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
154a0 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
154b0 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
154c0 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
154d0 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
154e0 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
154f0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
15500 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
15510 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
15520 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
15530 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
15540 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
15550 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
15560 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
15570 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
15580 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
15590 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
155a0 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
155b0 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
155c0 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
155d0 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  owid..**.** ^Thi
155e0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
155f0 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
15600 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
15610 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
15620 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
15630 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
15640 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
15650 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
15660 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15670 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74  t.  ^As of SQLit
15680 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
15690 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a   this routines.*
156a0 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61  * records the la
156b0 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20  st insert rowid 
156c0 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79  of both ordinary
156d0 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72   tables and [vir
156e0 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a  tual tables]..**
156f0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
15700 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
15710 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
15720 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
15730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
15740 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
15750 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
15760 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
15770 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
15780 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
15790 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
157a0 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
157b0 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
157c0 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
157d0 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
157e0 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
157f0 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
15800 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
15810 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
15820 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
15830 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
15840 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
15850 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
15860 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
15870 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
15880 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
15890 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
158a0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
158b0 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
158c0 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
158d0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
158e0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
158f0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
15900 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
15910 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
15920 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
15930 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
15940 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
15950 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
15960 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
15970 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
15980 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
15990 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
159a0 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
159b0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
159c0 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
159d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
159e0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
159f0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
15a00 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
15a10 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
15a20 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
15a30 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
15a40 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
15a50 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
15a60 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
15a70 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
15a80 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
15a90 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
15aa0 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
15ab0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
15ac0 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
15ad0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
15ae0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
15af0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
15b00 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
15b10 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
15b20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
15b30 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
15b40 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
15b50 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
15b60 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
15b70 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
15b80 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
15b90 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
15ba0 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
15bb0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
15bc0 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
15bd0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
15be0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
15bf0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
15c00 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
15c10 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
15c20 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
15c30 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
15c40 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
15c50 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
15c60 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
15c70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
15c80 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
15c90 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
15ca0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
15cb0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
15cc0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
15cd0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
15ce0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
15cf0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
15d00 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
15d10 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
15d20 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
15d30 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
15d40 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
15d50 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
15d60 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
15d70 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
15d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
15d90 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
15da0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
15db0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
15dc0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
15dd0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
15de0 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
15df0 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
15e00 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
15e10 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
15e20 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
15e30 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
15e40 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
15e50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15e60 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
15e70 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15e80 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
15e90 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
15ea0 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
15eb0 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
15ec0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
15ed0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
15ee0 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
15ef0 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
15f00 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
15f10 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
15f20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
15f30 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
15f40 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
15f50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
15f60 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
15f70 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
15f80 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
15f90 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
15fa0 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
15fb0 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
15fc0 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
15fd0 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
15fe0 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
15ff0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
16000 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
16010 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
16020 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
16030 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
16040 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
16050 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
16060 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
16070 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
16080 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
16090 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
160a0 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
160b0 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
160c0 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
160d0 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
160e0 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
160f0 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
16100 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
16110 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
16120 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
16130 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
16140 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
16150 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
16160 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
16170 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
16180 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
16190 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
161a0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
161b0 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
161c0 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
161d0 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
161e0 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
161f0 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
16200 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
16210 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
16220 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
16230 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
16240 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
16250 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
16260 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
16270 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
16280 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
16290 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
162a0 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
162b0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
162c0 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
162d0 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
162e0 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
162f0 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
16300 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
16310 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
16320 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
16330 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
16340 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
16350 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
16360 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
16370 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
16380 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
16390 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
163a0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
163b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
163c0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
163d0 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
163e0 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
163f0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
16400 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
16410 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
16420 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
16430 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
16440 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
16450 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
16460 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
16470 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
16480 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
16490 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
164a0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
164b0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
164c0 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
164d0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
164e0 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
164f0 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
16500 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
16510 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
16520 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
16530 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
16540 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
16550 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
16560 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
16570 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
16580 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
16590 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
165a0 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
165b0 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
165c0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
165d0 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
165e0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
165f0 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
16600 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
16610 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
16620 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
16630 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
16640 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
16650 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
16660 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
16670 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
16680 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
16690 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
166a0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
166b0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
166c0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
166d0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
166e0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
166f0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
16700 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
16710 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
16720 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
16730 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
16740 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
16750 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
16760 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
16770 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
16780 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16790 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
167a0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
167b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
167c0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
167d0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
167e0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
167f0 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
16800 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
16810 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
16820 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
16830 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
16840 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54  s opened..** ^(T
16850 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65  he count returne
16860 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
16870 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63  al_changes() inc
16880 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
16890 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43  s.** from all [C
168a0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
168b0 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74  trigger] context
168c0 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61  s and changes ma
168d0 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67  de by.** [foreig
168e0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20  n key actions]. 
168f0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
16900 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
16910 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
16920 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
16930 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
16940 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f  raints,.** do ro
16950 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54  llbacks or ABORT
16960 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20   processing, or 
16970 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f  [DROP TABLE] pro
16980 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a  cessing.  The.**
16990 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
169a0 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20  include rows of 
169b0 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20  views that fire 
169c0 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
169d0 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75  rigger],.** thou
169e0 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41  gh if the INSTEA
169f0 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b  D OF trigger mak
16a00 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74  es changes of it
16a10 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61  s own, those cha
16a20 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75  nges .** are cou
16a30 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  nted.)^.** ^The 
16a40 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
16a50 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
16a60 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e   counts the chan
16a70 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a  ges as soon as.*
16a80 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  * the statement 
16a90 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
16aa0 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
16ab0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
16ac0 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61   handle.** is pa
16ad0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
16ae0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
16af0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
16b00 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
16b10 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
16b20 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
16b30 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
16b40 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
16b50 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
16b60 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
16b70 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
16b80 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
16b90 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
16ba0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
16bb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
16bc0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
16bd0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
16be0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
16bf0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
16c00 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
16c10 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
16c20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
16c30 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
16c40 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
16c50 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
16c60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
16c70 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
16c80 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
16c90 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
16ca0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
16cb0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
16cc0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
16cd0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
16ce0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
16cf0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
16d00 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
16d10 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
16d20 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
16d30 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
16d40 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
16d50 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
16d60 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
16d70 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
16d80 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
16d90 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
16da0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
16db0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
16dc0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
16dd0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
16de0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
16df0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
16e00 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
16e10 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
16e20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
16e30 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
16e40 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
16e50 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
16e60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16e70 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
16e80 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
16e90 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
16ea0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
16eb0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
16ec0 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
16ed0 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
16ee0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
16ef0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
16f00 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16f10 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
16f20 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
16f30 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
16f40 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
16f50 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
16f60 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
16f70 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
16f80 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
16f90 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
16fa0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
16fb0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
16fc0 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
16fd0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
16fe0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
16ff0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
17000 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
17010 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
17020 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
17030 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
17040 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
17050 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
17060 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
17070 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
17080 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
17090 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
170a0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
170b0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
170c0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
170d0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
170e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
170f0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
17100 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
17110 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
17120 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
17130 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
17140 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
17150 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
17160 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
17170 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
17180 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
17190 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
171a0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
171b0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
171c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
171d0 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
171e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
171f0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
17200 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
17210 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
17220 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
17230 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
17240 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
17250 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
17260 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
17270 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17280 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
17290 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
172a0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
172b0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
172c0 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
172d0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
172e0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
172f0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
17300 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
17310 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
17320 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
17330 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
17340 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
17350 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
17360 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
17370 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
17380 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
17390 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
173a0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
173b0 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
173c0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
173d0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
173e0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
173f0 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
17400 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
17410 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
17420 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
17430 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
17440 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
17450 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
17460 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
17470 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
17480 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
17490 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
174a0 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
174b0 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
174c0 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
174d0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
174e0 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
174f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
17500 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
17510 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
17520 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
17530 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
17540 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
17550 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
17560 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
17570 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
17580 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
17590 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
175a0 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
175b0 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
175c0 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
175d0 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
175e0 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
175f0 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
17600 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
17610 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
17620 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
17630 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
17640 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
17650 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
17660 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
17670 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
17680 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
17690 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
176a0 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
176b0 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
176c0 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
176d0 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
176e0 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
176f0 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
17700 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
17710 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
17720 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
17730 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
17740 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
17750 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
17760 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
17770 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
17780 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
17790 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
177a0 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
177b0 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
177c0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
177d0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
177e0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
177f0 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
17800 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
17810 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
17820 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
17830 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
17840 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
17850 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
17860 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
17870 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
17880 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
17890 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
178a0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
178b0 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
178c0 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
178d0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
178e0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
178f0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
17900 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
17910 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
17920 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
17930 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
17940 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
17950 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
17960 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
17970 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
17980 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
17990 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
179a0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
179b0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
179c0 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
179d0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
179e0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
179f0 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
17a00 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
17a10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
17a20 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
17a30 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
17a40 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
17a50 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
17a60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17a70 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
17a80 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
17a90 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
17aa0 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
17ab0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
17ac0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
17ad0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
17ae0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
17af0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
17b00 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
17b10 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
17b20 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
17b30 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
17b40 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
17b50 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
17b60 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
17b70 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
17b80 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
17b90 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
17ba0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
17bb0 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
17bc0 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
17bd0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
17be0 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
17bf0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
17c00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
17c10 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
17c20 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
17c30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
17c40 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
17c50 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
17c60 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
17c70 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
17c80 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
17c90 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
17ca0 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
17cb0 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
17cc0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
17cd0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
17ce0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
17cf0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
17d00 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
17d10 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
17d20 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
17d30 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
17d40 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
17d50 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
17d60 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
17d70 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
17d80 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
17d90 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
17da0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
17db0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
17dc0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
17dd0 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
17de0 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  rned..** ^If the
17df0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17e00 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
17e10 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
17e20 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
17e30 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
17e40 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
17e50 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
17e60 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
17e70 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
17e80 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
17e90 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
17ea0 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
17eb0 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
17ec0 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
17ed0 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
17ee0 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
17ef0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
17f00 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
17f10 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
17f20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
17f30 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
17f40 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
17f50 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
17f60 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
17f70 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
17f80 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
17f90 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
17fa0 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
17fb0 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
17fc0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
17fd0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
17fe0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
17ff0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
18000 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
18010 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
18020 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
18030 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
18040 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
18050 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
18060 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
18070 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
18080 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
18090 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
180a0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
180b0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
180c0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
180d0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
180e0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
180f0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
18100 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
18110 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
18120 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
18130 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
18140 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
18150 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
18160 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
18170 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
18180 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
18190 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
181a0 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
181b0 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
181c0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
181d0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
181e0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
181f0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
18200 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
18210 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
18220 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
18230 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
18240 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
18250 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
18260 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
18270 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
18280 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
18290 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
182a0 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
182b0 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
182c0 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
182d0 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
182e0 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
182f0 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
18300 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
18310 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
18320 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
18330 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
18340 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
18350 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
18360 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
18370 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
18380 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
18390 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
183a0 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
183b0 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
183c0 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
183d0 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62    ^If it is unab
183e0 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
183f0 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
18400 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
18410 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
18420 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
18430 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
18440 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
18450 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
18460 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
18470 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
18480 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
18490 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
184a0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
184b0 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72  KED].  ^This err
184c0 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
184d0 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
184e0 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
184f0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
18500 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
18510 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
18520 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
18530 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
18540 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
18550 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
18560 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
18570 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
18580 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
18590 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
185a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
185b0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
185c0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
185d0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
185e0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
185f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
18600 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
18610 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
18620 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
18630 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
18640 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
18650 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
18660 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
18670 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
18680 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
18690 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
186a0 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
186b0 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
186c0 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
186d0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
186e0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
186f0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
18700 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
18710 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
18720 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
18730 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
18740 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
18750 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
18760 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
18770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18780 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
18790 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
187a0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
187b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
187c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
187d0 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
187e0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
187f0 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
18800 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18810 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
18820 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
18830 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
18840 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
18850 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
18860 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
18870 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
18880 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
18890 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
188a0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
188b0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
188c0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
188d0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
188e0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
188f0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
18900 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
18910 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
18920 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
18930 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
18940 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
18950 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
18960 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
18970 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
18980 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
18990 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
189a0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
189b0 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ED]..**.** ^Call
189c0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
189d0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
189e0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
189f0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
18a00 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
18a10 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
18a20 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
18a30 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
18a40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
18a50 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
18a60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18a70 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
18a80 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
18a90 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
18aa0 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
18ab0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
18ac0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
18ad0 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
18ae0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
18af0 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
18b00 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
18b10 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
18b20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
18b30 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
18b40 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
18b50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
18b60 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
18b70 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
18b80 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
18b90 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
18ba0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
18bb0 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
18bc0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
18bd0 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
18be0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
18bf0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
18c00 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
18c10 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
18c20 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
18c30 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
18c40 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
18c50 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
18c60 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
18c70 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
18c80 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
18c90 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
18ca0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
18cb0 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
18cc0 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
18cd0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
18ce0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
18cf0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
18d00 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
18d10 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
18d20 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
18d30 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
18d40 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
18d50 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
18d60 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
18d70 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
18d80 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
18d90 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
18da0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
18db0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
18dc0 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
18dd0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
18de0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
18df0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
18e00 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
18e10 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
18e20 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
18e30 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
18e40 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
18e50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
18e60 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
18e70 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
18e80 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
18e90 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
18ea0 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
18eb0 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
18ec0 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
18ed0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
18ee0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
18ef0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
18f00 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
18f10 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
18f20 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
18f30 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
18f40 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
18f50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
18f60 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
18f70 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
18f80 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
18f90 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
18fa0 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
18fb0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
18fc0 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
18fd0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
18fe0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
18ff0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
19000 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
19010 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
19020 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
19030 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
19040 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
19050 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
19060 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
19070 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
19080 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
19090 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
190a0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
190b0 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
190c0 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
190d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
190e0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
190f0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
19100 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
19110 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
19120 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
19130 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
19140 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
19150 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
19160 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
19170 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
19180 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
19190 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
191a0 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
191b0 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
191c0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
191d0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
191e0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
191f0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
19200 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
19210 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
19220 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
19230 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19240 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
19250 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19260 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
19270 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
19280 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
19290 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
192a0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
192b0 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
192c0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
192d0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
192e0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
192f0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
19300 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
19310 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
19320 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
19330 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
19340 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
19350 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
19360 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
19370 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
19380 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
19390 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
193a0 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
193b0 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
193c0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
193d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
193e0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
193f0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
19400 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
19410 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
19420 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
19430 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
19440 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
19450 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
19460 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
19470 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
19480 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
19490 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
194a0 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
194b0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
194c0 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
194d0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
194e0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
194f0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
19500 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
19510 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
19520 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
19530 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19540 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
19550 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
19560 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
19570 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
19580 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
19590 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
195a0 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
195b0 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
195c0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
195d0 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
195e0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
195f0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
19600 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
19610 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
19620 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
19630 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
19640 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
19650 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
19660 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
19670 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
19680 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
19690 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
196a0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
196b0 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
196c0 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
196d0 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
196e0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
196f0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
19700 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
19710 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
19720 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
19730 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
19740 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
19750 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
19760 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
19770 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
19780 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
19790 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
197a0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
197b0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
197c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
197d0 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
197e0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
197f0 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
19800 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
19810 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
19820 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
19830 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
19840 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
19850 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
19860 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
19870 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
19880 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
19890 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
198a0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
198b0 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
198c0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
198d0 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
198e0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
198f0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
19900 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
19910 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
19920 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
19930 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
19940 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
19950 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19960 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
19970 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
19980 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
19990 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
199a0 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
199b0 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
199c0 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
199d0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
199e0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
199f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19a00 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
19a10 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
19a20 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
19a30 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
19a40 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
19a50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
19a60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19a70 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
19a80 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
19a90 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
19aa0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
19ab0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
19ac0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
19ad0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
19ae0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
19af0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
19b00 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
19b10 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
19b20 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
19b30 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
19b40 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
19b50 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
19b60 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
19b70 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
19b80 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
19b90 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
19ba0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
19bb0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
19bc0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
19bd0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
19be0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
19bf0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
19c00 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
19c10 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
19c20 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
19c30 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
19c40 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
19c50 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
19c60 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
19c70 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
19c80 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
19c90 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
19ca0 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
19cb0 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
19cc0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
19cd0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
19ce0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
19cf0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
19d00 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
19d10 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
19d20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
19d30 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
19d40 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
19d50 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
19d60 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
19d70 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
19d80 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
19d90 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
19da0 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
19db0 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
19dc0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
19dd0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
19de0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
19df0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
19e00 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
19e10 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
19e20 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
19e30 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
19e40 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
19e50 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
19e60 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
19e70 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
19e80 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
19e90 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
19ea0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
19eb0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
19ec0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
19ed0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
19ee0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
19ef0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
19f00 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
19f10 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
19f20 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
19f30 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
19f40 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
19f50 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
19f60 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
19f70 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
19f80 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
19f90 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
19fa0 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
19fb0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
19fc0 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
19fd0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
19fe0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
19ff0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1a000 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1a010 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1a020 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1a030 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1a040 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1a050 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1a060 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1a070 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1a080 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1a090 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1a0a0 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
1a0b0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1a0c0 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1a0d0 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1a0e0 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1a0f0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1a100 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1a110 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1a120 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1a130 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1a140 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1a150 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1a160 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1a170 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1a180 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1a190 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1a1a0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1a1b0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1a1c0 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1a1d0 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1a1e0 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1a1f0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1a200 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1a210 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1a220 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1a230 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1a240 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a250 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1a260 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1a270 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1a280 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1a290 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1a2a0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1a2b0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1a2c0 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1a2d0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1a2e0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1a2f0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1a300 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1a310 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1a320 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1a330 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1a340 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1a350 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1a360 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1a370 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1a380 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1a390 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1a3a0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1a3b0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1a3c0 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1a3d0 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1a3e0 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
1a3f0 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
1a400 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1a410 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1a420 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1a430 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
1a440 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
1a450 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1a460 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1a470 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
1a480 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
1a490 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
1a4a0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
1a4b0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
1a4c0 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
1a4d0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1a4e0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1a4f0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1a500 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
1a510 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
1a520 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1a530 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
1a540 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
1a550 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
1a560 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
1a570 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
1a580 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
1a590 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
1a5a0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
1a5b0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
1a5c0 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
1a5d0 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
1a5e0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
1a5f0 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
1a600 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
1a610 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
1a620 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
1a630 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
1a640 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
1a650 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
1a660 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
1a670 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
1a680 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
1a690 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
1a6a0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
1a6b0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
1a6c0 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
1a6d0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
1a6e0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
1a6f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1a700 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1a710 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1a720 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1a730 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
1a740 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1a750 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1a760 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1a770 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1a780 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1a790 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1a7a0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
1a7b0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
1a7c0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
1a7d0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
1a7e0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
1a7f0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
1a800 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
1a810 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1a820 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1a830 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1a840 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1a850 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1a860 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1a870 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1a880 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1a890 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1a8a0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1a8b0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1a8c0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1a8d0 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
1a8e0 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1a8f0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1a900 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1a910 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1a920 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1a930 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1a940 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1a950 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1a960 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
1a970 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1a980 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1a990 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1a9a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a9b0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1a9c0 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1a9d0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1a9e0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1a9f0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1aa00 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1aa10 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1aa20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1aa30 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1aa40 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1aa50 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1aa60 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1aa70 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1aa80 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1aa90 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1aaa0 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1aab0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1aac0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1aad0 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1aae0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1aaf0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1ab00 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1ab10 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1ab20 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1ab30 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1ab40 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1ab50 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1ab60 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1ab70 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1ab80 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1ab90 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1aba0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1abb0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1abc0 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1abd0 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1abe0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1abf0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1ac00 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1ac10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1ac20 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1ac30 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  inter..**.** ^Ca
1ac40 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1ac50 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1ac60 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1ac70 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1ac80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1ac90 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1aca0 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1acb0 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1acc0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1acd0 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1ace0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1acf0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1ad00 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1ad10 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1ad20 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1ad30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1ad40 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1ad50 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1ad60 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1ad70 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1ad80 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1ad90 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1ada0 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1adb0 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1adc0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1add0 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1ade0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1adf0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1ae00 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1ae10 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1ae20 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1ae30 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1ae40 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1ae50 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1ae60 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1ae70 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1ae80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1ae90 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1aea0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1aeb0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1aec0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1aed0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1aee0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
1aef0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1af00 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1af10 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1af20 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61  location to be a
1af30 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c  t least N bytes,
1af40 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
1af50 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1af60 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  ter.  The memory
1af70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
1af80 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65  e resized is the
1af90 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1afa0 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20  ter.)^ ^ If the 
1afb0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1afc0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1afd0 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  oc().** is a NUL
1afe0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
1aff0 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
1b000 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
1b010 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
1b020 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e  alloc(N) where N
1b030 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   is the second p
1b040 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b050 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1b060 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64  * ^If the second
1b070 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1b080 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1b090 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1b0a0 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1b0b0 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1b0c0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1b0d0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1b0e0 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65  e3_free(P) where
1b0f0 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20   P is the first 
1b100 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1b110 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1b120 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
1b130 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20  loc() returns a 
1b140 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1b150 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1b160 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1b170 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1b180 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69   NULL if suffici
1b190 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e  ent memory is un
1b1a0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1b1b0 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1b1c0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1b1d0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1b1e0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1b1f0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1b200 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1b210 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1b220 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1b230 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1b240 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b250 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1b260 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1b270 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1b280 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
1b290 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  urns NULL, then 
1b2a0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1b2b0 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66  tion.** is not f
1b2c0 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  reed..**.** ^The
1b2d0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
1b2e0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1b2f0 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  oc() and sqlite3
1b300 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
1b310 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
1b320 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
1b330 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
1b340 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
1b350 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
1b360 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
1b370 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
1b380 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1b390 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
1b3a0 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
1b3b0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
1b3c0 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
1b3d0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
1b3e0 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
1b3f0 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
1b400 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
1b410 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
1b420 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
1b430 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
1b440 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
1b450 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
1b460 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
1b470 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
1b480 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
1b490 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1b4a0 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
1b4b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
1b4c0 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1b4d0 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
1b4e0 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
1b4f0 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
1b500 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1b510 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1b520 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1b530 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1b540 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1b550 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1b560 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1b570 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1b580 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1b590 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1b5a0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1b5b0 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1b5c0 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1b5d0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1b5e0 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
1b5f0 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
1b600 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1b610 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1b620 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1b630 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1b640 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1b650 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1b660 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1b670 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1b680 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1b690 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1b6a0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1b6b0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1b6c0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1b6d0 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1b6e0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1b6f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1b700 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1b710 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1b720 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1b730 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1b740 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1b750 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1b760 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1b770 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1b780 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1b790 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1b7a0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1b7b0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1b7c0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1b7d0 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
1b7e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1b7f0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1b800 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
1b810 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
1b820 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
1b830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b840 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
1b850 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
1b860 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
1b870 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
1b880 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
1b890 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
1b8a0 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
1b8b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1b8c0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1b8d0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1b8e0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
1b8f0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
1b900 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
1b910 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1b920 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
1b930 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1b940 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1b950 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1b960 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1b970 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
1b980 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
1b990 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
1b9a0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
1b9b0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
1b9c0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1b9d0 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
1b9e0 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
1b9f0 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
1ba00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1ba10 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
1ba20 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1ba30 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
1ba40 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
1ba50 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1ba60 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1ba70 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1ba80 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1ba90 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
1baa0 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
1bab0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
1bac0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
1bad0 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
1bae0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
1baf0 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
1bb00 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
1bb10 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
1bb20 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
1bb30 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
1bb40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1bb50 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
1bb60 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
1bb70 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
1bb80 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
1bb90 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
1bba0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1bbb0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
1bbc0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
1bbd0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
1bbe0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1bbf0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
1bc00 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
1bc10 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
1bc20 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1bc30 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
1bc40 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1bc50 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
1bc60 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
1bc70 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1bc80 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
1bc90 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
1bca0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1bcb0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
1bcc0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
1bcd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
1bce0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
1bcf0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
1bd00 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
1bd10 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
1bd20 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
1bd30 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
1bd40 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
1bd50 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
1bd60 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
1bd70 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1bd80 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
1bd90 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
1bda0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
1bdb0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
1bdc0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
1bdd0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
1bde0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
1bdf0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
1be00 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
1be10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
1be20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1be30 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
1be40 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
1be50 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
1be60 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
1be70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
1be80 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1be90 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
1bea0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
1beb0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
1bec0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
1bed0 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
1bee0 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
1bef0 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
1bf00 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
1bf10 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
1bf20 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
1bf30 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
1bf40 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
1bf50 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
1bf60 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
1bf70 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1bf80 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
1bf90 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
1bfa0 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
1bfb0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
1bfc0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
1bfd0 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
1bfe0 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
1bff0 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
1c000 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1c010 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1c020 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
1c030 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1c040 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1c050 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1c060 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1c070 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1c080 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1c090 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1c0a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1c0b0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1c0c0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1c0d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1c0e0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1c0f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1c100 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1c110 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1c120 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1c130 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1c140 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1c150 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1c160 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1c170 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1c180 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1c190 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1c1a0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1c1b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1c1c0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1c1d0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1c1e0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1c1f0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1c200 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1c210 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1c220 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1c230 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1c240 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1c250 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1c260 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1c270 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1c280 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1c290 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1c2a0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1c2b0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1c2c0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1c2d0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1c2e0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1c2f0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1c300 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1c310 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1c320 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1c330 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1c340 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1c350 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1c360 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1c370 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1c380 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1c390 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1c3a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1c3b0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1c3c0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1c3d0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1c3e0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1c3f0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1c400 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1c410 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1c420 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1c430 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1c440 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1c450 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1c460 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1c470 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1c480 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1c490 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1c4a0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1c4b0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1c4c0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1c4d0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1c4e0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1c4f0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1c500 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c510 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1c520 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1c530 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1c540 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1c550 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1c560 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1c570 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1c580 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1c590 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1c5a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1c5b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1c5c0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1c5d0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1c5e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c5f0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1c600 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1c610 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1c620 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1c630 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1c640 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1c650 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1c660 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1c670 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1c680 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1c690 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1c6a0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1c6b0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1c6c0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1c6d0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1c6e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1c6f0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1c700 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1c710 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1c720 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1c730 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1c740 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1c750 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1c760 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1c770 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1c780 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1c790 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1c7a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1c7b0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1c7c0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1c7d0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1c7e0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1c7f0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1c800 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1c810 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1c820 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1c830 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1c840 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1c850 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1c860 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1c870 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1c880 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1c890 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1c8a0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1c8b0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1c8c0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1c8d0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1c8e0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1c8f0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1c900 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1c910 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1c920 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1c930 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1c940 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1c950 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1c960 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1c970 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1c980 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1c990 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1c9a0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1c9b0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1c9c0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1c9d0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1c9e0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1c9f0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1ca00 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1ca10 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1ca20 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1ca30 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1ca40 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1ca50 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1ca60 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1ca70 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1ca80 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1ca90 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1caa0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1cab0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1cac0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1cad0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1cae0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1caf0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1cb00 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1cb10 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1cb20 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1cb30 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1cb40 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1cb50 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1cb60 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1cb70 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1cb80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1cb90 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1cba0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1cbb0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1cbc0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1cbd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1cbe0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1cbf0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1cc00 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1cc10 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1cc20 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1cc30 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1cc40 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1cc50 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1cc60 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1cc70 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1cc80 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1cc90 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1cca0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1ccb0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1ccc0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1ccd0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1cce0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1ccf0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1cd00 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1cd10 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1cd20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1cd30 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1cd40 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1cd50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cd60 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1cd70 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1cd80 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1cd90 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1cda0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1cdb0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1cdc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1cdd0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1cde0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1cdf0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1ce00 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1ce10 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1ce20 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ce30 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1ce40 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1ce50 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1ce60 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1ce70 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1ce80 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1ce90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1cea0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1ceb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1cec0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1ced0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1cee0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1cef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1cf00 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1cf10 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1cf20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1cf30 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1cf40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cf50 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1cf60 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1cf70 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1cf80 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1cf90 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1cfa0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1cfb0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1cfc0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1cfd0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1cfe0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1cff0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1d000 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1d010 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1d020 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1d030 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1d040 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1d050 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1d060 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d070 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1d080 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1d090 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1d0a0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1d0b0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1d0c0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1d0d0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1d0e0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1d0f0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1d100 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1d110 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1d120 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1d130 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1d140 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1d150 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d160 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1d170 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1d180 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1d190 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1d1a0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1d1b0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1d1c0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1d1d0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1d1e0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1d1f0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1d200 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1d210 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1d220 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1d230 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1d240 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1d250 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1d260 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1d270 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1d280 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1d290 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1d2a0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1d2b0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1d2c0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1d2d0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1d2e0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1d2f0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1d300 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1d310 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1d320 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1d330 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1d340 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1d350 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1d360 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1d370 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1d380 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1d390 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
1d3a0 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
1d3b0 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
1d3c0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1d3d0 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1d3e0 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1d3f0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1d400 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1d410 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1d420 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1d430 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1d440 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1d450 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1d460 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1d470 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1d480 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1d490 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1d4a0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1d4b0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1d4c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1d4d0 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1d4e0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1d4f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1d500 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1d510 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1d520 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1d530 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1d540 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1d550 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1d560 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1d570 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1d580 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1d590 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1d5a0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1d5b0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1d5c0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1d5d0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1d5e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d5f0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1d600 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1d610 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1d620 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1d630 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1d640 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1d650 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1d660 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1d670 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1d680 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1d690 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1d6a0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1d6b0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1d6c0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1d6d0 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1d6e0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1d6f0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1d700 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1d710 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1d720 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d730 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1d740 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1d750 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1d760 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1d770 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1d780 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1d790 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d7a0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1d7b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1d7c0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1d7d0 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1d7e0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1d7f0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1d800 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1d810 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1d820 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1d830 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1d840 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1d850 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1d860 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d870 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1d880 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1d890 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1d8a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1d8b0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1d8c0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1d8d0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1d8e0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1d8f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1d900 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1d910 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1d920 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1d930 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d940 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1d950 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1d960 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1d970 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1d980 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1d990 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1d9a0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1d9b0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1d9c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1d9d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1d9e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1d9f0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1da00 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1da10 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1da20 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1da30 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1da40 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1da50 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1da60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1da70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1da80 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1da90 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1daa0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1dab0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1dac0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1dad0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1dae0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1daf0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1db00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1db10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1db20 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1db30 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1db40 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1db50 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1db60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1db70 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1db80 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1db90 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1dba0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1dbb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1dbc0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1dbd0 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1dbe0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1dbf0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1dc00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dc10 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1dc20 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1dc30 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1dc40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1dc50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dc60 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1dc70 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1dc80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1dc90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1dca0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dcb0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1dcc0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1dcd0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1dce0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1dcf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dd00 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1dd10 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1dd20 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1dd30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1dd40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1dd50 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1dd60 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1dd70 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1dd80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1dd90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1dda0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1ddb0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1ddc0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1ddd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1dde0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1ddf0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1de00 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1de10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1de20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1de30 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1de40 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1de50 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1de60 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1de70 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1de80 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1de90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1dea0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1deb0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1dec0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1ded0 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1dee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1def0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1df00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1df10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1df20 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1df30 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1df40 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1df50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1df60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1df70 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1df80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1df90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1dfa0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1dfb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1dfc0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1dfd0 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1dfe0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1dff0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e000 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e010 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1e020 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1e030 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1e040 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e050 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e060 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1e070 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1e080 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1e090 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e0a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e0b0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1e0c0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1e0d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1e0e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e0f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e100 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1e110 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1e120 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e130 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e150 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1e160 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1e170 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1e180 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1e190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e1a0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1e1b0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1e1c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1e1d0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1e1e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e1f0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1e200 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1e210 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1e220 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1e230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1e240 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1e250 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1e260 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1e270 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1e280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1e290 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1e2a0 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1e2b0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
1e2c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
1e2d0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
1e2e0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1e2f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1e300 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
1e310 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
1e320 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
1e330 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
1e340 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
1e350 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
1e360 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1e370 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1e380 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1e390 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1e3a0 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1e3b0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1e3c0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1e3d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1e3e0 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1e3f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1e400 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e410 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1e420 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
1e430 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1e440 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
1e450 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1e460 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
1e470 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
1e480 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
1e490 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
1e4a0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1e4b0 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
1e4c0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1e4d0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1e4e0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1e4f0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1e500 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1e510 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1e520 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1e530 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1e540 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
1e550 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1e560 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1e570 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1e580 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1e590 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
1e5a0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
1e5b0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
1e5c0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
1e5d0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
1e5e0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1e5f0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
1e600 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
1e610 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
1e620 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1e630 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
1e640 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1e650 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
1e660 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
1e670 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
1e680 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
1e690 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
1e6a0 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
1e6b0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
1e6c0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
1e6d0 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
1e6e0 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
1e6f0 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
1e700 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
1e710 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1e720 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
1e730 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
1e740 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
1e750 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
1e760 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
1e770 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
1e780 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
1e790 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
1e7a0 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
1e7b0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
1e7c0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
1e7d0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1e7e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
1e7f0 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
1e800 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
1e810 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
1e820 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
1e830 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
1e840 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
1e850 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
1e860 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
1e870 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1e880 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
1e890 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1e8a0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
1e8b0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
1e8c0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
1e8d0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1e8e0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
1e8f0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
1e900 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
1e910 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
1e920 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
1e930 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
1e940 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
1e950 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
1e960 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
1e970 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
1e980 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1e990 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
1e9a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1e9b0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
1e9c0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
1e9d0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
1e9e0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
1e9f0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
1ea00 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
1ea10 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
1ea20 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1ea30 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
1ea40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
1ea50 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1ea60 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
1ea70 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
1ea80 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1ea90 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1eaa0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1eab0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1eac0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
1ead0 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
1eae0 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
1eaf0 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  k X..**.** ^Only
1eb00 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1eb10 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1eb20 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1eb30 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1eb40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1eb50 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1eb60 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1eb70 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1eb80 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1eb90 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1eba0 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1ebb0 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1ebc0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1ebd0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1ebe0 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1ebf0 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1ec00 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1ec10 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1ec20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1ec30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ec40 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1ec50 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1ec60 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1ec70 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1ec80 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1ec90 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1eca0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1ecb0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1ecc0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1ecd0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1ece0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1ecf0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1ed00 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1ed10 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1ed20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1ed30 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1ed40 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1ed50 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1ed60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ed70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ed80 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1ed90 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1eda0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1edb0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1edc0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1edd0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1ede0 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
1edf0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1ee00 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1ee10 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
1ee20 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1ee30 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
1ee40 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
1ee50 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
1ee60 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1ee70 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
1ee80 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
1ee90 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
1eea0 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
1eeb0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
1eec0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1eed0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1eee0 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1eef0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1ef00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1ef10 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1ef20 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1ef30 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1ef40 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1ef50 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
1ef60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1ef70 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
1ef80 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
1ef90 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
1efa0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1efb0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
1efc0 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
1efd0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
1efe0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1eff0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1f000 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1f010 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
1f020 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
1f030 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
1f040 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
1f050 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
1f060 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
1f070 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1f080 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
1f090 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
1f0a0 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
1f0b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1f0c0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
1f0d0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1f0e0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1f0f0 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
1f100 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
1f110 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1f120 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
1f130 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
1f140 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
1f150 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
1f160 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
1f170 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
1f180 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
1f190 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
1f1a0 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
1f1b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
1f1c0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
1f1d0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
1f1e0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
1f1f0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
1f200 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1f210 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
1f220 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
1f230 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1f240 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
1f250 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
1f260 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
1f270 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
1f280 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
1f290 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
1f2a0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
1f2b0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1f2c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f2d0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
1f2e0 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
1f2f0 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
1f300 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
1f310 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
1f320 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
1f330 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1f340 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f350 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
1f360 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
1f370 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
1f380 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
1f390 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
1f3a0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
1f3b0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
1f3c0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
1f3d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f3e0 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
1f3f0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
1f400 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
1f410 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
1f420 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
1f430 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
1f440 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
1f450 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
1f460 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1f470 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
1f480 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1f490 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1f4a0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
1f4b0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1f4c0 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
1f4d0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1f4e0 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
1f4f0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
1f500 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1f510 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
1f520 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1f530 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
1f540 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
1f550 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
1f560 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
1f570 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
1f580 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1f590 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1f5a0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1f5b0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
1f5c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1f5d0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1f5e0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1f5f0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
1f600 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
1f610 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
1f620 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
1f630 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
1f640 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
1f650 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
1f660 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
1f670 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
1f680 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
1f690 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1f6a0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1f6b0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1f6c0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1f6d0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1f6e0 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1f6f0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1f700 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1f710 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1f720 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1f730 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
1f740 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
1f750 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
1f760 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
1f770 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
1f780 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1f790 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1f7a0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
1f7b0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
1f7c0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
1f7d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1f7e0 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
1f7f0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
1f800 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
1f810 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
1f820 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
1f830 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
1f840 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
1f850 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
1f860 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
1f870 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
1f880 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
1f890 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1f8a0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1f8b0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1f8c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f8d0 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1f8e0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1f8f0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1f900 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1f910 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1f920 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1f930 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1f940 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1f950 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
1f960 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1f970 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1f980 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1f990 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f9a0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1f9b0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1f9c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1f9d0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1f9e0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1f9f0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1fa00 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1fa10 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1fa20 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
1fa30 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1fa40 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1fa50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1fa60 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
1fa70 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
1fa80 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1fa90 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
1faa0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1fab0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
1fac0 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
1fad0 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
1fae0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1faf0 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
1fb00 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1fb10 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
1fb20 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
1fb30 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
1fb40 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
1fb50 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
1fb60 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
1fb70 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
1fb80 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
1fb90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1fba0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1fbb0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1fbc0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
1fbd0 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
1fbe0 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
1fbf0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1fc00 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
1fc10 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1fc20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
1fc30 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
1fc40 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1fc50 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
1fc60 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
1fc70 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1fc80 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
1fc90 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
1fca0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
1fcb0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1fcc0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1fcd0 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
1fce0 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
1fcf0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1fd00 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
1fd10 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1fd20 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1fd30 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1fd40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1fd50 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1fd60 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1fd70 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1fd80 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1fd90 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1fda0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1fdb0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1fdc0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1fdd0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1fde0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1fdf0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1fe00 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1fe10 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1fe20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1fe30 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1fe40 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1fe50 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1fe60 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1fe70 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1fe80 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1fe90 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
1fea0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1feb0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1fec0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
1fed0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1fee0 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
1fef0 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
1ff00 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
1ff10 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
1ff20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
1ff30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ff40 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
1ff50 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
1ff60 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
1ff70 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
1ff80 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
1ff90 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
1ffa0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
1ffb0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
1ffc0 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
1ffd0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
1ffe0 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
1fff0 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
20000 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
20010 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
20020 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
20030 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
20040 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
20050 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
20060 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
20070 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
20080 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
20090 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
200a0 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
200b0 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
200c0 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
200d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
200e0 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
200f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
20100 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
20110 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
20120 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
20130 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
20140 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
20150 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
20160 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
20170 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
20180 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
20190 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
201a0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
201b0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
201c0 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
201d0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
201e0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
201f0 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
20200 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
20210 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
20220 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
20230 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
20240 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
20250 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
20260 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
20270 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
20280 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
20290 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
202a0 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
202b0 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
202c0 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
202d0 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
202e0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
202f0 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
20300 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
20310 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
20320 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
20330 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
20340 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
20350 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
20360 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
20370 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
20380 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
20390 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
203a0 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
203b0 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
203c0 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
203d0 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
203e0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
203f0 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
20400 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
20410 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
20420 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
20430 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
20440 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
20450 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
20460 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
20470 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
20480 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
20490 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
204a0 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
204b0 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
204c0 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f  ive path. .** ^O
204d0 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
204e0 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
204f0 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
20500 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
20510 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
20520 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a  (e.g. "C:")..**.
20530 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
20540 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
20550 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
20560 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
20570 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
20580 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
20590 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
205a0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
205b0 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
205c0 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
205d0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
205e0 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  n]..** SQLite in
205f0 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c  terprets the fol
20600 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65  lowing three que
20610 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
20620 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
20630 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
20640 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
20650 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
20660 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
20670 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
20680 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
20690 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
206a0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
206b0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
206c0 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
206d0 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
206e0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
206f0 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
20700 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
20710 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
20720 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
20730 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
20740 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
20750 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
20760 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
20770 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
20780 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
20790 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
207a0 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
207b0 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
207c0 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
207d0 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
207e0 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
207f0 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
20800 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
20810 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
20820 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
20830 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
20840 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
20850 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
20860 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
20870 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
20880 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
20890 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
208a0 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
208b0 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
208c0 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
208d0 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
208e0 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
208f0 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
20900 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
20910 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20920 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
20930 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
20940 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
20950 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20960 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
20970 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
20980 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
20990 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
209a0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
209b0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
209c0 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
209d0 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
209e0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
209f0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
20a00 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
20a10 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
20a20 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
20a30 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
20a40 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
20a50 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
20a60 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
20a70 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
20a80 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
20a90 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
20aa0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
20ab0 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
20ac0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
20ad0 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
20ae0 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
20af0 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
20b00 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
20b10 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
20b20 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
20b30 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
20b40 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
20b50 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
20b60 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
20b70 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
20b80 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
20b90 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
20ba0 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
20bb0 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
20bc0 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
20bd0 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
20be0 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
20bf0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
20c00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
20c10 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
20c20 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
20c30 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
20c40 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
20c50 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
20c60 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
20c70 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
20c80 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
20c90 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
20ca0 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
20cb0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
20cc0 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
20cd0 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
20ce0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
20cf0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20d00 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
20d10 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
20d20 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
20d30 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
20d40 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
20d50 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
20d60 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
20d70 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
20d80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
20d90 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
20da0 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
20db0 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
20dc0 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
20dd0 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
20de0 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
20df0 61 76 69 6f 75 72 20 72 65 71 75 65 73 74 65 64  aviour requested
20e00 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
20e10 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
20e20 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
20e30 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
20e40 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20  DCACHE flag..** 
20e50 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
20e60 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
20e70 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
20e80 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
20e90 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
20ea0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
20eb0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
20ec0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
20ed0 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
20ee0 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
20ef0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
20f00 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
20f10 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
20f20 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
20f30 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
20f40 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
20f50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
20f60 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
20f70 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
20f80 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
20f90 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
20fa0 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
20fb0 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
20fc0 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
20fd0 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
20fe0 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
20ff0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
21000 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
21010 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
21020 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
21030 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
21040 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
21050 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
21060 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
21070 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
21080 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
21090 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
210a0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
210b0 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
210c0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
210d0 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
210e0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
210f0 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
21100 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21110 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
21120 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
21130 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21140 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
21150 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
21160 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
21170 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
21180 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
21190 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
211a0 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
211b0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
211c0 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
211d0 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
211e0 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
211f0 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
21200 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
21210 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
21220 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
21230 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
21240 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
21250 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
21260 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
21270 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
21280 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
21290 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
212a0 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
212b0 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
212c0 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
212d0 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
212e0 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
212f0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
21300 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
21310 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
21320 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
21330 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
21340 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
21350 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
21360 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
21370 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
21380 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
21390 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
213a0 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
213b0 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
213c0 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
213d0 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
213e0 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
213f0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
21400 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
21410 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20  nolock <td>.**  
21420 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
21430 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
21440 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
21450 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
21460 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74  x-nolock"..** <t
21470 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
21480 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
21490 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
214a0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
214b0 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
214c0 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
214d0 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
214e0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
214f0 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
21500 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
21510 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
21520 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
21530 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
21540 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
21550 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
21560 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
21570 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
21580 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
21590 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
215a0 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
215b0 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
215c0 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
215d0 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
215e0 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
215f0 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
21600 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
21610 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
21620 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
21630 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
21640 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
21650 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
21660 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
21670 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
21680 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
21690 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
216a0 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
216b0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
216c0 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
216d0 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
216e0 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
216f0 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
21700 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
21710 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
21720 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
21730 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
21740 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
21750 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
21760 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
21770 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
21780 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21790 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
217a0 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
217b0 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
217c0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
217d0 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
217e0 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
217f0 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
21800 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
21810 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
21820 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
21830 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
21840 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
21850 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
21860 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
21870 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
21880 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
21890 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
218a0 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
218b0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
218c0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
218d0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
218e0 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
218f0 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
21900 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
21910 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
21920 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
21930 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
21940 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21950 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
21960 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
21970 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
21980 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
21990 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
219a0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
219b0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
219c0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
219d0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
219e0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
219f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
21a00 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
21a10 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
21a20 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
21a30 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
21a40 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
21a50 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
21a60 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
21a70 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
21a80 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
21a90 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
21aa0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
21ab0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
21ac0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
21ad0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
21ae0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
21af0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
21b00 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
21b10 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
21b20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
21b30 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
21b40 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
21b50 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
21b60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
21b70 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
21b80 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
21b90 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
21ba0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
21bb0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
21bc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
21bd0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
21be0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
21bf0 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
21c00 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
21c10 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
21c20 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
21c30 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
21c40 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
21c50 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
21c60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
21c70 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
21c80 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
21c90 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
21ca0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
21cb0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
21cc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
21cd0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
21ce0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
21cf0 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
21d00 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
21d10 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
21d20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
21d30 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
21d40 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
21d50 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
21d60 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
21d70 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
21d80 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
21d90 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
21da0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
21db0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
21dc0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
21dd0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
21de0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
21df0 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
21e00 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
21e10 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
21e20 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
21e30 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
21e40 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
21e50 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
21e60 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
21e70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
21e80 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
21e90 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21ea0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
21eb0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
21ec0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
21ed0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
21ee0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
21ef0 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
21f00 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
21f10 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
21f20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
21f30 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
21f40 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
21f50 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
21f60 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
21f70 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
21f80 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
21f90 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
21fa0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
21fb0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
21fc0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
21fd0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
21fe0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
21ff0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22000 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
22010 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
22020 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
22030 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
22040 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
22050 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
22060 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
22070 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
22080 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
22090 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
220a0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
220b0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
220c0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
220d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
220e0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
220f0 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
22100 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
22110 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22120 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
22130 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
22140 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
22150 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
22160 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
22170 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
22180 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
22190 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
221a0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
221b0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
221c0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
221d0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
221e0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
221f0 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
22200 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
22210 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
22220 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
22230 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
22240 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
22250 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
22260 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
22270 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
22280 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
22290 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
222a0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
222b0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
222c0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
222d0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
222e0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
222f0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
22300 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
22310 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
22320 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
22330 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
22340 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
22350 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
22360 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
22370 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
22380 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
22390 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
223a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
223b0 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
223c0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
223d0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
223e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
223f0 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
22400 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
22410 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
22420 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
22430 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
22440 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
22450 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
22460 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
22470 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
22480 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
22490 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
224a0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
224b0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
224c0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
224d0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
224e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
224f0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
22500 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
22510 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
22520 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
22530 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
22540 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
22550 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
22560 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
22570 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
22580 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
22590 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
225a0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
225b0 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
225c0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
225d0 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
225e0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
225f0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
22600 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
22610 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
22620 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
22630 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
22640 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
22650 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
22660 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22670 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
22680 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
22690 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
226a0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
226b0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
226c0 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
226d0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
226e0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
226f0 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
22700 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
22710 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
22720 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
22730 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
22740 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
22750 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
22760 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
22770 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
22780 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
22790 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
227a0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
227b0 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
227c0 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
227d0 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
227e0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
227f0 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
22800 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
22810 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
22820 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
22830 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
22840 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
22850 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
22860 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
22870 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
22880 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
22890 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
228a0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
228b0 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
228c0 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
228d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
228e0 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
228f0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
22900 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
22910 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
22920 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
22930 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
22940 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
22950 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
22960 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
22970 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
22980 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
22990 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
229a0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
229b0 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
229c0 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
229d0 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
229e0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
229f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
22a00 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
22a10 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
22a20 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
22a30 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
22a40 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
22a50 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
22a60 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
22a70 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
22a80 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
22a90 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
22aa0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
22ab0 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
22ac0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
22ad0 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
22ae0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
22af0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
22b00 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
22b10 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
22b20 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
22b30 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
22b40 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
22b50 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
22b60 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
22b70 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
22b80 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
22b90 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
22ba0 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
22bb0 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
22bc0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
22bd0 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
22be0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
22bf0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
22c00 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
22c10 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
22c20 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
22c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
22c40 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
22c50 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
22c60 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
22c70 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
22c80 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
22c90 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
22ca0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63  lite3*);.const c
22cb0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
22cc0 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
22cd0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
22ce0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
22cf0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
22d00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22d10 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
22d20 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
22d30 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
22d40 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
22d50 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
22d60 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
22d70 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
22d80 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
22d90 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
22da0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
22db0 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
22dc0 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
22dd0 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
22de0 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
22df0 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
22e00 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
22e10 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
22e20 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
22e30 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
22e40 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
22e50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22e60 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
22e70 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
22e80 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
22e90 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
22ea0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
22eb0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
22ec0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
22ed0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
22ee0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
22ef0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
22f00 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
22f10 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
22f20 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
22f30 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
22f40 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
22f50 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
22f60 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
22f70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
22f80 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
22f90 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
22fa0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
22fb0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
22fc0 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
22fd0 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
22fe0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
22ff0 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
23000 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
23010 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
23020 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
23030 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
23040 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
23050 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
23060 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
23070 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
23080 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
23090 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
230a0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
230b0 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
230c0 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
230d0 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
230e0 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
230f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
23100 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
23110 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
23120 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
23130 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
23140 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
23150 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
23160 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
23170 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
23180 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
23190 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
231a0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
231b0 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
231c0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
231d0 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
231e0 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
231f0 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
23200 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
23210 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
23220 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
23230 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
23240 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
23250 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
23260 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
23270 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
23280 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
23290 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
232a0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
232b0 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
232c0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
232d0 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
232e0 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
232f0 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
23300 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
23310 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
23320 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
23330 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
23340 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
23350 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
23360 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
23370 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
23380 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
23390 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
233a0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
233b0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
233c0 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
233d0 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
233e0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
233f0 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
23400 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
23410 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
23420 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
23430 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
23440 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
23450 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
23460 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
23470 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
23480 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
23490 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
234a0 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
234b0 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
234c0 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
234d0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
234e0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
234f0 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
23500 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
23510 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
23520 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
23530 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
23540 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
23550 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
23560 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
23570 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
23580 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
23590 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
235a0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
235b0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
235c0 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
235d0 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
235e0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
235f0 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
23600 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
23610 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
23620 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
23630 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
23640 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
23650 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
23660 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
23670 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
23680 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
23690 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
236a0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
236b0 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
236c0 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
236d0 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
236e0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
236f0 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
23700 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
23710 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23720 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
23730 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
23740 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
23750 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
23760 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
23770 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
23780 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
23790 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
237a0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
237b0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
237c0 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
237d0 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
237e0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
237f0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
23800 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
23810 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23820 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
23830 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
23840 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
23850 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
23860 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
23870 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
23880 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
23890 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
238a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
238b0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
238c0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
238d0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
238e0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
238f0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
23900 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
23910 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
23920 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
23930 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
23940 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
23950 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
23960 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
23970 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
23980 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
23990 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
239a0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
239b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
239c0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
239d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
239e0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
239f0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
23a00 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
23a10 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
23a20 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
23a30 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
23a40 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
23a50 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
23a60 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
23a70 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
23a80 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
23a90 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
23aa0 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
23ab0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
23ac0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
23ad0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
23ae0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
23af0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23b00 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
23b10 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
23b20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
23b30 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
23b40 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
23b50 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
23b60 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23b70 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
23b80 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
23b90 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
23ba0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
23bb0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
23bc0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
23bd0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
23be0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
23bf0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
23c00 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
23c10 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
23c20 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
23c30 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
23c40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
23c50 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
23c60 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
23c70 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
23c80 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
23c90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
23ca0 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
23cb0 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
23cc0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
23cd0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
23ce0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
23cf0 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
23d00 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
23d10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23d20 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
23d30 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
23d40 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
23d50 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
23d60 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
23d70 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
23d80 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
23d90 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
23da0 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
23db0 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
23dc0 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
23dd0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
23de0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
23df0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
23e00 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
23e10 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
23e20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
23e30 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
23e40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
23e50 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
23e60 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
23e70 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
23e80 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
23e90 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
23ea0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
23eb0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
23ec0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
23ed0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
23ee0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
23ef0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
23f00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23f10 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
23f20 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
23f30 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23f40 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
23f50 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
23f60 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
23f70 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
23f80 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
23f90 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
23fa0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
23fb0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
23fc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
23fd0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
23fe0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
23ff0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
24000 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
24010 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
24020 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
24030 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
24040 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
24050 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
24060 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
24070 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
24080 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
24090 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
240a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
240b0 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
240c0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
240d0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
240e0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
240f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
24100 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
24110 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
24120 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
24130 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
24140 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
24150 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
24160 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
24170 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
24180 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
24190 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
241a0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
241b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
241c0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
241d0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
241e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
241f0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
24200 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
24210 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24220 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
24230 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
24240 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24250 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
24260 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
24270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24280 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
24290 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
242a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
242b0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
242c0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
242d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
242e0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
242f0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
24300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24310 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
24320 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
24330 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
24340 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
24350 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
24360 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
24370 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
24380 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
24390 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
243a0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
243b0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
243c0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
243d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
243e0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
243f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24400 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
24410 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
24420 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
24430 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
24440 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24450 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
24460 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
24470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24480 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
24490 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
244a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
244b0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
244c0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
244d0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
244e0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
244f0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
24500 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
24510 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
24520 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
24530 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
24540 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
24550 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
24560 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
24570 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
24580 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
24590 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
245a0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
245b0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
245c0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
245d0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
245e0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
245f0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
24600 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
24610 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
24620 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
24630 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
24640 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
24650 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
24660 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
24670 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
24680 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
24690 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
246a0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
246b0 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
246c0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
246d0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
246e0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
246f0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
24700 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
24710 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
24720 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
24730 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
24740 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
24750 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
24760 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
24770 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
24780 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
24790 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
247a0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
247b0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
247c0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
247d0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
247e0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
247f0 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
24800 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
24810 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
24820 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
24830 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
24840 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
24850 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
24860 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
24870 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
24880 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
24890 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
248a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
248b0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
248c0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
248d0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
248e0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
248f0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
24900 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
24910 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
24920 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
24930 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
24940 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
24950 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
24960 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24970 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
24980 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
24990 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
249a0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
249b0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
249c0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
249d0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
249e0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
249f0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
24a00 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
24a10 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
24a20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
24a30 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
24a40 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
24a50 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
24a60 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
24a70 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
24a80 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
24a90 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
24aa0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
24ab0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
24ac0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
24ad0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
24ae0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
24af0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
24b00 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
24b10 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
24b20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
24b30 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
24b40 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
24b50 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
24b60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
24b70 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
24b80 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
24b90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
24ba0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
24bb0 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
24bc0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
24bd0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
24be0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
24bf0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
24c00 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
24c10 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
24c20 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
24c30 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
24c40 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
24c50 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
24c60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
24c70 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
24c80 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
24c90 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
24ca0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
24cb0 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
24cc0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
24cd0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
24ce0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
24cf0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
24d00 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
24d10 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
24d20 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
24d30 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
24d40 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
24d50 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
24d60 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
24d70 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
24d80 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
24d90 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
24da0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
24db0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
24dc0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
24dd0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
24de0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
24df0 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
24e00 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
24e10 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
24e20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24e30 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
24e40 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
24e50 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
24e60 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
24e70 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
24e80 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
24e90 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
24ea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24eb0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
24ec0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
24ed0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
24ee0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
24ef0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
24f00 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
24f10 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
24f20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
24f30 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
24f40 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
24f50 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
24f60 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
24f70 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
24f80 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
24f90 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
24fa0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
24fb0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
24fc0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
24fd0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
24fe0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
24ff0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
25000 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
25010 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
25020 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
25030 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
25040 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
25050 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
25060 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
25070 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
25080 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
25090 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
250a0 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
250b0 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
250c0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
250d0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
250e0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
250f0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
25100 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
25110 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
25120 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
25130 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
25140 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
25150 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
25160 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
25170 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
25180 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
25190 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
251a0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
251b0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
251c0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
251d0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
251e0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
251f0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
25200 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
25210 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
25220 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
25230 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
25240 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
25250 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
25260 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
25270 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
25280 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
25290 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
252a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
252b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
252c0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
252d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
252e0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
252f0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
25300 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
25310 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
25320 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
25330 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
25340 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
25350 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
25360 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
25370 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
25380 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
25390 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
253a0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
253b0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
253c0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
253d0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
253e0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
253f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25400 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25410 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
25420 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
25430 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
25440 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
25450 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
25460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
25470 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
25480 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
25490 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
254a0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
254b0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
254c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
254d0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
254e0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
254f0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
25500 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
25510 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
25520 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
25530 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
25540 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
25550 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
25560 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
25570 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
25580 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
25590 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
255a0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
255b0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
255c0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
255d0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
255e0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
255f0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
25600 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
25610 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
25620 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
25630 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
25640 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
25650 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
25660 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25670 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
25680 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
25690 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
256a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
256b0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
256c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
256d0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
256e0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
256f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
25700 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
25710 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
25720 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
25730 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
25740 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
25750 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
25760 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
25770 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
25780 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
25790 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
257a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
257b0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
257c0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
257d0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
257e0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
257f0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
25800 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
25810 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
25820 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
25830 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
25840 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
25850 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
25860 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
25870 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
25880 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
25890 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
258a0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
258b0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
258c0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
258d0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
258e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
258f0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
25900 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
25910 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
25920 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
25930 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
25940 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
25950 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
25960 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
25970 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
25980 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25990 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
259a0 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
259b0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
259c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
259d0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
259e0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
259f0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
25a00 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
25a10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
25a20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
25a30 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
25a40 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
25a50 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
25a60 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
25a70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
25a80 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
25a90 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
25aa0 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
25ab0 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
25ac0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
25ad0 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
25ae0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
25af0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
25b00 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
25b10 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
25b20 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
25b30 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
25b40 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
25b50 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
25b60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
25b70 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
25b80 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
25b90 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
25ba0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
25bb0 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
25bc0 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
25bd0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
25be0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
25bf0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
25c00 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
25c10 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
25c20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
25c30 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
25c40 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
25c50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
25c60 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
25c70 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
25c80 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
25c90 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
25ca0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
25cb0 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
25cc0 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
25cd0 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
25ce0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
25cf0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
25d00 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
25d10 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
25d20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
25d30 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
25d40 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
25d50 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
25d60 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
25d70 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
25d80 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
25d90 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
25da0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
25db0 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
25dc0 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
25dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25de0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
25df0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
25e00 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
25e10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
25e20 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
25e30 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
25e40 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
25e50 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
25e60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25e70 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
25e80 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
25e90 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
25ea0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
25eb0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
25ec0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
25ed0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
25ee0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
25ef0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25f00 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
25f10 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
25f20 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
25f30 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
25f40 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
25f50 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
25f60 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
25f70 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
25f80 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
25f90 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
25fa0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
25fb0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
25fc0 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
25fd0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
25fe0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
25ff0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
26000 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
26010 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
26020 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
26030 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
26040 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
26050 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
26060 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
26070 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
26080 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
26090 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
260a0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
260b0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
260c0 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
260d0 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
260e0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
260f0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
26100 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
26110 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
26120 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
26130 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
26140 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
26150 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
26160 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
26170 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
26180 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
26190 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
261a0 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
261b0 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
261c0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
261d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
261e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
261f0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
26200 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
26210 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
26220 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26230 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
26240 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26250 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
26260 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
26270 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
26280 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
26290 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
262a0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
262b0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
262c0 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
262d0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
262e0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
262f0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
26300 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
26310 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
26320 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
26330 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
26340 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
26350 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
26360 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
26370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26380 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
26390 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
263a0 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
263b0 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
263c0 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
263d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
263e0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
263f0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
26400 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
26410 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
26420 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
26430 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
26440 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
26450 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
26460 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
26470 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
26480 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
26490 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
264a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
264b0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
264c0 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
264d0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
264e0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
264f0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
26500 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
26510 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
26520 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
26530 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
26540 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26550 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
26560 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
26570 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
26580 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26590 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
265a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
265b0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
265c0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
265d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
265e0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
265f0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
26600 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
26610 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
26620 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
26630 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
26640 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
26650 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
26660 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
26670 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
26680 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
26690 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
266a0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
266b0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
266c0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
266d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
266e0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
266f0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
26700 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
26710 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
26720 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
26730 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
26740 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
26750 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
26760 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
26770 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
26780 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
26790 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
267a0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
267b0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
267c0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
267d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
267e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
267f0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
26800 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
26810 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
26820 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
26830 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
26840 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
26850 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
26860 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
26870 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
26880 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
26890 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
268a0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
268b0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
268c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
268d0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
268e0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
268f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
26900 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
26910 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
26920 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
26930 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
26940 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
26950 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
26960 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
26970 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
26980 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26990 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
269a0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
269b0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
269c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
269d0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
269e0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
269f0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
26a00 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
26a10 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
26a20 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
26a30 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
26a40 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
26a50 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
26a60 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
26a70 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
26a80 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
26a90 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
26aa0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
26ab0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
26ac0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26ad0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
26ae0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
26af0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
26b00 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
26b10 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
26b20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
26b30 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
26b40 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
26b50 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
26b60 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
26b70 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
26b80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
26b90 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
26ba0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
26bb0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
26bc0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
26bd0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
26be0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
26bf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
26c00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
26c10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26c20 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
26c30 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
26c40 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
26c50 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
26c60 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
26c70 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
26c80 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
26c90 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
26ca0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
26cb0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
26cc0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
26cd0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
26ce0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
26cf0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
26d00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26d10 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
26d20 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
26d30 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
26d40 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
26d50 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
26d60 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
26d70 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
26d80 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
26d90 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
26da0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
26db0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
26dc0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
26dd0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
26de0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
26df0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
26e00 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
26e10 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
26e20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
26e30 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
26e40 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
26e50 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
26e60 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
26e70 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
26e80 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
26e90 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
26ea0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
26eb0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
26ec0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
26ed0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
26ee0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
26ef0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
26f00 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
26f10 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
26f20 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
26f30 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
26f40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
26f50 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
26f60 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
26f70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
26f80 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
26f90 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
26fa0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
26fb0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
26fc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
26fd0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
26fe0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
26ff0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
27000 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
27010 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
27020 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
27030 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
27040 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
27050 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
27060 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
27070 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
27080 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
27090 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
270a0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
270b0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
270c0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
270d0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
270e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
270f0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
27100 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
27110 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
27120 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
27130 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
27140 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
27150 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
27160 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
27170 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
27180 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
27190 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
271a0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
271b0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
271c0 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
271d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
271e0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
271f0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
27200 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
27210 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
27220 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
27230 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
27240 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
27250 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
27260 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
27270 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
27280 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
27290 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
272a0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
272b0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
272c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
272d0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
272e0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
272f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
27300 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
27310 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27320 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
27330 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
27340 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
27350 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
27360 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
27370 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
27380 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
27390 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
273a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
273b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
273c0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
273d0 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
273e0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
273f0 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
27400 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
27410 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
27420 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
27430 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
27440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27450 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20  t16() then that 
27460 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
27470 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
27480 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
27490 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
274a0 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
274b0 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
274c0 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
274d0 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
274e0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
274f0 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
27500 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
27510 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
27520 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
27530 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
27540 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
27550 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
27560 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
27570 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
27580 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
27590 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
275a0 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
275b0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
275c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
275d0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
275e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
275f0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
27600 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
27610 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27620 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
27630 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
27640 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
27650 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
27660 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
27670 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
27680 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
27690 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
276a0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
276b0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
276c0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
276d0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
276e0 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
276f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
27700 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
27710 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
27720 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
27730 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
27740 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
27750 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
27760 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
27770 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
27780 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
27790 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
277a0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
277b0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
277c0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
277d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
277e0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
277f0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
27800 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
27810 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
27820 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
27830 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
27840 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
27850 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
27860 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
27870 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
27880 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27890 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
278a0 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
278b0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
278c0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
278d0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
278e0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
278f0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
27900 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
27910 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
27920 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
27930 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
27940 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
27950 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
27960 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
27970 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
27980 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
27990 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
279a0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
279b0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
279c0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
279d0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
279e0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
279f0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
27a00 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
27a10 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
27a20 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
27a30 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
27a40 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
27a50 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
27a60 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
27a70 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
27a80 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
27a90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27aa0 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
27ab0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
27ac0 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
27ad0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
27ae0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
27af0 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
27b00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27b10 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
27b20 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
27b30 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
27b40 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
27b50 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
27b60 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
27b70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27b80 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
27b90 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
27ba0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
27bb0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
27bc0 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
27bd0 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
27be0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
27bf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
27c00 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
27c10 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
27c20 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
27c30 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
27c40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27c50 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
27c60 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
27c70 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
27c80 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
27c90 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
27ca0 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
27cb0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
27cc0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
27cd0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
27ce0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
27cf0 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
27d00 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
27d10 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
27d20 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
27d30 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
27d40 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
27d50 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
27d60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27d70 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
27d80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
27d90 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
27da0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
27db0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
27dc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27dd0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
27de0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
27df0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
27e00 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
27e10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27e20 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
27e30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
27e40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27e50 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
27e60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
27e70 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
27e80 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
27e90 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
27ea0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
27eb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
27ec0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
27ed0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
27ee0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
27ef0 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
27f00 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
27f10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
27f20 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
27f30 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
27f40 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
27f50 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
27f60 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27f70 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
27f80 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
27f90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27fa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
27fb0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
27fc0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
27fd0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
27fe0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
27ff0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
28000 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
28010 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
28020 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
28030 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
28040 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
28050 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28060 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
28070 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
28080 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
28090 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
280a0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
280b0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
280c0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
280d0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
280e0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
280f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
28100 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
28110 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
28120 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
28130 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
28140 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
28150 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
28160 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
28170 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
28180 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
28190 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
281a0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
281b0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
281c0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
281d0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
281e0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
281f0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
28200 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
28210 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
28220 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
28230 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
28240 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
28250 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
28260 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28270 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
28280 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
28290 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
282a0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
282b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
282c0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
282d0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
282e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
282f0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
28300 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
28310 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28320 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
28330 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
28340 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
28350 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
28360 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
28370 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
28380 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
28390 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
283a0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
283b0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
283c0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
283d0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
283e0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
283f0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
28400 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
28410 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
28420 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
28430 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
28440 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
28450 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
28460 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
28470 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
28480 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
28490 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
284a0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
284b0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
284c0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
284d0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
284e0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
284f0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
28500 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
28510 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
28520 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
28530 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
28540 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
28550 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
28560 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
28570 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
28580 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
28590 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
285a0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
285b0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
285c0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
285d0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
285e0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
285f0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
28600 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
28610 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
28620 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
28630 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
28640 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
28650 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
28660 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
28670 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28680 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
28690 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
286a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
286b0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
286c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
286d0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
286e0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
286f0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
28700 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
28710 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28720 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28730 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
28740 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
28750 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
28760 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
28770 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
28780 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
28790 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
287a0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
287b0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
287c0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
287d0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
287e0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
287f0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
28800 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
28810 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
28820 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
28830 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
28840 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
28850 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
28860 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
28870 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
28880 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
28890 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
288a0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
288b0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
288c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
288d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
288e0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
288f0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
28900 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
28910 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28920 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
28930 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
28940 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
28950 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
28960 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28970 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
28980 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
28990 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
289a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
289b0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
289c0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
289d0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
289e0 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
289f0 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
28a00 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
28a10 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
28a20 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
28a30 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
28a40 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
28a50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28a60 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
28a70 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
28a80 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
28a90 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
28aa0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28ab0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
28ac0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
28ad0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28ae0 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
28af0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
28b00 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
28b10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
28b20 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
28b30 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
28b40 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
28b50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28b60 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
28b70 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
28b80 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
28b90 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
28ba0 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
28bb0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
28bc0 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
28bd0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
28be0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
28bf0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
28c00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
28c10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
28c20 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
28c30 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
28c40 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
28c50 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
28c60 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
28c70 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
28c80 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
28c90 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
28ca0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
28cb0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
28cc0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
28cd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
28ce0 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
28cf0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
28d00 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
28d10 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
28d20 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
28d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
28d40 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
28d50 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
28d60 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
28d70 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
28d80 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
28d90 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
28da0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
28db0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
28dc0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
28dd0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
28de0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
28df0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
28e00 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
28e10 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
28e20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
28e30 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
28e40 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
28e50 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
28e60 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
28e70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
28e80 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
28e90 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
28ea0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
28eb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
28ec0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
28ed0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
28ee0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
28ef0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
28f00 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
28f10 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
28f20 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
28f30 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
28f40 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
28f50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28f60 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
28f70 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
28f80 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
28f90 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
28fa0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
28fb0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
28fc0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
28fd0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
28fe0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
28ff0 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
29000 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
29010 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
29020 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
29030 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
29040 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
29050 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
29060 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
29070 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
29080 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
29090 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
290a0 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
290b0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
290c0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
290d0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
290e0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
290f0 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
29100 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
29110 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
29120 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
29130 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
29140 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
29150 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
29170 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
29180 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
29190 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
291a0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
291b0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
291c0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
291d0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
291e0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
291f0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
29200 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
29210 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
29220 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
29230 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
29240 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
29250 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
29260 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
29270 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
29280 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
29290 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
292a0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
292b0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
292c0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
292d0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
292e0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
292f0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
29300 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
29310 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
29320 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
29330 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
29340 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
29350 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
29360 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
29370 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
29380 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
29390 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
293a0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
293b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
293c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
293d0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
293e0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
293f0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
29400 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
29410 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
29420 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
29430 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
29440 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
29450 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
29460 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
29470 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
29480 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
29490 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
294a0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
294b0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
294c0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
294d0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
294e0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
294f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
29500 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
29510 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
29520 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
29530 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
29540 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
29550 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
29560 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
29570 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
29580 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
29590 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
295a0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
295b0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
295c0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
295d0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
295e0 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
295f0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
29600 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
29610 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
29620 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
29630 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
29640 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
29650 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
29660 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
29670 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
29680 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
29690 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
296a0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
296b0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
296c0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
296d0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
296e0 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
296f0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
29700 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
29710 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
29720 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
29730 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
29740 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
29750 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
29760 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
29770 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
29780 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
29790 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
297a0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
297b0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
297c0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
297d0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
297e0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
297f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
29800 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
29810 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
29820 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
29830 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
29840 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
29850 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
29860 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
29870 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
29880 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
29890 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
298a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
298b0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
298c0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
298d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
298e0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
298f0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
29900 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
29910 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
29920 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
29930 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
29940 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
29950 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
29960 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
29970 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
29980 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
29990 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
299a0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
299b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
299c0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
299d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
299e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
299f0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
29a00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
29a10 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
29a20 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
29a30 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29a40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
29a50 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
29a60 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
29a70 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
29a80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
29a90 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
29aa0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
29ab0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
29ac0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
29ad0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
29ae0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
29af0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29b00 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
29b10 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
29b20 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29b30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
29b40 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
29b50 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
29b60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
29b70 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
29b80 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
29b90 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
29ba0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
29bb0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
29bc0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
29bd0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
29be0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
29bf0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
29c00 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
29c10 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
29c20 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
29c30 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
29c40 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
29c50 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
29c60 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
29c70 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
29c80 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
29c90 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
29ca0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
29cb0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
29cc0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29cd0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
29ce0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
29cf0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
29d00 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
29d10 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
29d20 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
29d30 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
29d40 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
29d50 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
29d60 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
29d70 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
29d80 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
29d90 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
29da0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
29db0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
29dc0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
29dd0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
29de0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
29df0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
29e00 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
29e10 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
29e20 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
29e30 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
29e40 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
29e50 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
29e60 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
29e70 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
29e80 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
29e90 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
29ea0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
29eb0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
29ec0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
29ed0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
29ee0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
29ef0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
29f00 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
29f10 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
29f20 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
29f30 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
29f40 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
29f50 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
29f60 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
29f70 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
29f80 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
29f90 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
29fa0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
29fb0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
29fc0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
29fd0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
29fe0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
29ff0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2a000 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2a010 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a020 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2a030 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a040 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2a050 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2a060 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a070 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
2a080 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2a090 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2a0a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2a0b0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2a0c0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2a0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a0e0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2a0f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2a100 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2a110 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2a120 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2a130 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2a140 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2a150 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2a160 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2a170 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2a180 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2a190 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2a1a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2a1b0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2a1c0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2a1d0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2a1e0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2a1f0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2a200 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2a210 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2a220 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2a230 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2a240 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2a250 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a260 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2a270 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2a280 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2a290 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2a2a0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2a2b0 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2a2c0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2a2d0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2a2e0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2a2f0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2a300 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2a310 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2a320 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2a330 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2a340 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2a350 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2a360 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2a370 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2a380 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2a390 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2a3a0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2a3b0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2a3c0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2a3d0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2a3e0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2a3f0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2a400 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2a410 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2a420 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2a430 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2a440 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2a450 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2a460 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2a470 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2a480 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2a490 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2a4a0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2a4b0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2a4c0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2a4d0 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2a4e0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2a4f0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2a500 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2a510 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2a520 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2a530 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2a540 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2a550 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2a560 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2a570 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2a580 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2a590 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2a5a0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2a5b0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2a5c0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2a5d0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2a5e0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2a5f0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2a600 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2a610 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2a620 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2a630 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2a640 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2a650 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2a660 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2a670 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2a680 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2a690 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2a6a0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2a6b0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2a6c0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2a6d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2a6e0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2a6f0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2a700 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2a710 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2a720 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2a730 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2a740 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2a750 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2a760 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2a770 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2a780 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2a790 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2a7a0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2a7b0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2a7c0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2a7d0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2a7e0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2a7f0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2a800 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2a810 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2a820 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2a830 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2a840 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2a850 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2a860 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2a870 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2a880 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2a890 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2a8a0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2a8b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2a8c0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2a8d0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2a8e0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2a8f0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2a900 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2a910 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2a920 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2a930 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2a940 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2a950 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2a960 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2a970 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2a980 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2a990 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a9a0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2a9b0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2a9c0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2a9d0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2a9e0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2a9f0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2aa00 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2aa10 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2aa20 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2aa30 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2aa40 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2aa50 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2aa60 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2aa70 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2aa80 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2aa90 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2aaa0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2aab0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2aac0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2aad0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2aae0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2aaf0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2ab00 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2ab10 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2ab20 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2ab30 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2ab40 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2ab50 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2ab60 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2ab70 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2ab80 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2ab90 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2aba0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2abb0 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2abc0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2abd0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2abe0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2abf0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2ac00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2ac10 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2ac20 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2ac30 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2ac40 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2ac50 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2ac60 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2ac70 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2ac80 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2ac90 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2aca0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2acb0 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2acc0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2acd0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2ace0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2acf0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2ad00 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2ad10 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2ad20 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2ad30 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2ad40 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2ad50 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2ad60 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2ad70 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2ad80 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2ad90 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2ada0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2adb0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2adc0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2add0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2ade0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2adf0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2ae00 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2ae10 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2ae20 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2ae30 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2ae40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2ae50 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2ae60 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2ae70 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2ae80 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2ae90 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2aea0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2aeb0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2aec0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2aed0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2aee0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2aef0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2af00 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2af10 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2af20 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2af30 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2af40 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2af50 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2af60 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2af70 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2af80 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2af90 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2afa0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2afb0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2afc0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2afd0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2afe0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2aff0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2b000 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2b010 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2b020 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2b030 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2b040 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2b050 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2b060 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2b070 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2b080 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2b090 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2b0a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b0b0 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2b0c0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2b0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b0e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2b0f0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2b100 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2b110 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2b120 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2b130 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2b140 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2b150 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2b160 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2b170 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2b180 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2b190 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2b1a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2b1b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b1c0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2b1d0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2b1e0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2b1f0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2b200 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
2b210 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2b220 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2b230 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
2b240 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2b250 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
2b260 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2b270 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
2b280 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2b290 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2b2a0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2b2b0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2b2c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2b2d0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2b2e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2b2f0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2b300 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2b310 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2b320 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2b330 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2b340 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2b350 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2b360 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2b370 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
2b380 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2b390 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
2b3a0 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
2b3b0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
2b3c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2b3d0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
2b3e0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
2b3f0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2b400 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
2b410 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
2b420 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
2b430 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b440 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
2b450 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
2b460 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
2b470 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
2b480 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
2b490 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
2b4a0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2b4b0 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
2b4c0 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
2b4d0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
2b4e0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
2b4f0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
2b500 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2b510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2b520 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
2b530 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2b540 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b550 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2b560 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2b570 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
2b580 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
2b590 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
2b5a0 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
2b5b0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
2b5c0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
2b5d0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
2b5e0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
2b5f0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2b600 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
2b610 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
2b620 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
2b630 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
2b640 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
2b650 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
2b660 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
2b670 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
2b680 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
2b690 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
2b6a0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
2b6b0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
2b6c0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
2b6d0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
2b6e0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
2b6f0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
2b700 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
2b710 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
2b720 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
2b730 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
2b740 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
2b750 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
2b760 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
2b770 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
2b780 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
2b790 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
2b7a0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2b7b0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
2b7c0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
2b7d0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2b7e0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
2b7f0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
2b800 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
2b810 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
2b820 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
2b830 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
2b840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
2b850 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
2b860 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2b870 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
2b880 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
2b890 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
2b8a0 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
2b8b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2b8c0 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
2b8d0 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
2b8e0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
2b8f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2b900 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2b910 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2b920 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2b930 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2b940 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2b950 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2b960 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2b970 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2b980 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2b990 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2b9a0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2b9b0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2b9c0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2b9d0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2b9e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b9f0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2ba00 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2ba10 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2ba20 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2ba30 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2ba40 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2ba50 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2ba60 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2ba70 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2ba80 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2ba90 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2baa0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2bab0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2bac0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2bad0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2bae0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2baf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2bb00 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2bb10 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2bb20 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2bb30 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2bb40 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2bb50 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2bb60 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2bb70 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2bb80 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2bb90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2bba0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2bbb0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2bbc0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2bbd0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2bbe0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2bbf0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2bc00 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2bc10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2bc20 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2bc30 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2bc40 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2bc50 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2bc60 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2bc70 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2bc80 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2bc90 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2bca0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2bcb0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2bcc0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2bcd0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2bce0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2bcf0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2bd00 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2bd10 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2bd20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2bd30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2bd40 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2bd50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2bd60 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2bd70 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2bd80 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2bd90 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2bda0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2bdb0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2bdc0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2bdd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2bde0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2bdf0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2be00 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2be10 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2be20 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2be30 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2be40 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2be50 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2be60 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2be70 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2be80 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2be90 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2bea0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2beb0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2bec0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2bed0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2bee0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2bef0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2bf00 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2bf10 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2bf20 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2bf30 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2bf40 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2bf50 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2bf60 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2bf70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2bf80 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2bf90 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2bfa0 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2bfb0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2bfc0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2bfd0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2bfe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bff0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2c000 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2c010 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2c020 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2c030 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2c040 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2c050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c060 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2c070 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2c080 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2c090 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2c0a0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2c0b0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2c0c0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2c0d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c0e0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2c0f0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2c100 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2c110 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2c120 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2c130 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2c140 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2c150 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2c160 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2c170 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2c180 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2c190 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2c1a0 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2c1b0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2c1c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2c1d0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2c1e0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2c1f0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2c200 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2c210 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2c220 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2c230 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2c240 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2c250 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2c260 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2c270 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2c280 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2c290 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2c2a0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2c2b0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2c2c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2c2d0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2c2e0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2c2f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2c300 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2c310 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2c320 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2c330 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2c340 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2c350 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2c360 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2c370 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c380 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2c390 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2c3a0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2c3b0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2c3c0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2c3d0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2c3e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2c3f0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2c400 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2c410 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2c420 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c430 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2c440 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2c450 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2c460 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2c470 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2c480 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2c490 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2c4a0 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2c4b0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2c4c0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2c4d0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2c4e0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2c4f0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2c500 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2c510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c520 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2c530 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c540 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2c550 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2c560 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2c570 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2c580 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2c590 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2c5a0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2c5b0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2c5c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c5d0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2c5e0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2c5f0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2c600 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2c610 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2c620 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2c630 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2c640 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2c650 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2c660 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2c670 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2c680 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2c690 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2c6a0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2c6b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c6c0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2c6d0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c6e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c6f0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2c700 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2c710 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2c720 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2c730 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2c740 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2c750 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c760 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2c770 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2c780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2c790 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2c7a0 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2c7b0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2c7c0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2c7d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c7e0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2c7f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2c800 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2c810 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2c820 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2c830 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2c840 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2c850 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2c860 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2c870 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2c880 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2c890 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2c8a0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2c8b0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2c8c0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2c8d0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2c8e0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2c8f0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2c900 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2c910 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2c920 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2c930 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2c940 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2c950 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2c960 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2c970 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2c980 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2c990 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2c9a0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2c9b0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2c9c0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2c9d0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2c9e0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2c9f0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2ca00 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2ca10 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2ca20 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2ca30 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2ca40 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2ca50 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2ca60 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2ca70 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2ca80 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2ca90 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2caa0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2cab0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2cac0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2cad0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2cae0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2caf0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2cb00 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2cb10 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2cb20 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2cb30 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2cb40 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2cb50 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2cb60 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2cb70 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2cb80 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2cb90 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2cba0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2cbb0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2cbc0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2cbd0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
2cbe0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
2cbf0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2cc00 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2cc10 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2cc20 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2cc30 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2cc40 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2cc50 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2cc60 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
2cc70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2cc80 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2cc90 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
2cca0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2ccb0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2ccc0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
2ccd0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2cce0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2ccf0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2cd00 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2cd10 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2cd20 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2cd30 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2cd40 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
2cd50 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2cd60 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2cd70 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2cd80 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2cd90 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
2cda0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2cdb0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2cdc0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2cdd0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2cde0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2cdf0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2ce00 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2ce10 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2ce20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2ce30 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2ce40 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2ce50 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2ce60 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2ce70 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2ce80 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2ce90 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2cea0 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2ceb0 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2cec0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2ced0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2cee0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2cef0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2cf00 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2cf10 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2cf20 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2cf30 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2cf40 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2cf50 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2cf60 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2cf70 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2cf80 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2cf90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2cfa0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2cfb0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2cfc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2cfd0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2cfe0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2cff0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2d000 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2d010 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2d020 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2d030 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2d040 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2d050 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2d060 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2d070 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2d080 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2d090 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2d0a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2d0b0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2d0c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2d0d0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2d0e0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2d0f0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2d100 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2d110 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2d120 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2d130 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2d140 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2d150 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2d160 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2d170 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2d180 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2d190 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2d1a0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2d1b0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2d1c0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2d1d0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2d1e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d1f0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2d200 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d210 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2d220 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2d230 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2d240 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2d250 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2d260 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2d270 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2d280 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2d290 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2d2a0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2d2b0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2d2c0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2d2d0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2d2e0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2d2f0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2d300 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2d310 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2d320 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2d330 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2d340 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2d350 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2d360 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2d370 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2d380 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2d390 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2d3a0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2d3b0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2d3c0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2d3d0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2d3e0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2d3f0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2d400 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2d410 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2d420 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2d430 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2d440 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2d450 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2d460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2d470 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2d480 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d490 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2d4a0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2d4b0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2d4c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2d4d0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2d4e0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2d4f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2d500 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2d510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d520 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2d530 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2d540 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2d550 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2d560 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2d570 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2d580 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2d590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d5a0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2d5b0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2d5c0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2d5d0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2d5e0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2d5f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2d600 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2d610 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2d620 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2d630 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2d640 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2d650 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2d660 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2d670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2d680 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2d690 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2d6a0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2d6b0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2d6c0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2d6d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2d6e0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2d6f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d700 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2d710 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2d720 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2d730 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2d740 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2d750 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2d760 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2d770 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2d780 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2d790 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2d7a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2d7b0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2d7c0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2d7d0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2d7e0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2d7f0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2d800 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2d810 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2d820 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2d830 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
2d840 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2d850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2d860 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2d870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2d880 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2d890 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2d8a0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2d8b0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2d8c0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2d8d0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2d8e0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2d8f0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2d900 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2d910 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2d920 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2d930 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2d940 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2d950 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2d960 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2d970 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2d980 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2d990 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2d9a0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2d9b0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2d9c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2d9d0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2d9e0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2d9f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2da00 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2da10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2da20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2da30 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
2da40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2da50 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
2da60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2da70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2da80 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2da90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2daa0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2dab0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2dac0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2dad0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2dae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2daf0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
2db00 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2db10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2db20 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2db30 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2db40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2db50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
2db60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2db70 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2db80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2db90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2dba0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2dbb0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
2dbc0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
2dbd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2dbe0 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
2dbf0 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
2dc00 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
2dc10 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2dc20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2dc30 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2dc40 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2dc50 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2dc60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2dc70 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2dc80 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2dc90 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2dca0 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
2dcb0 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
2dcc0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
2dcd0 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
2dce0 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
2dcf0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2dd00 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
2dd10 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
2dd20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2dd30 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
2dd40 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
2dd50 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
2dd60 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
2dd70 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
2dd80 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
2dd90 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2dda0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2ddb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ddc0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
2ddd0 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
2dde0 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
2ddf0 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
2de00 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
2de10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2de20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
2de30 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
2de40 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
2de50 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
2de60 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2de70 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
2de80 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
2de90 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
2dea0 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
2deb0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
2dec0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
2ded0 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
2dee0 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
2def0 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
2df00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2df10 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
2df20 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
2df30 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
2df40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
2df50 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
2df60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2df70 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
2df80 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
2df90 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
2dfa0 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
2dfb0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
2dfc0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
2dfd0 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
2dfe0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
2dff0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
2e000 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
2e010 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
2e020 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
2e030 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2e040 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
2e050 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
2e060 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
2e070 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
2e080 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
2e090 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
2e0a0 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
2e0b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
2e0c0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2e0d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e0e0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
2e0f0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2e100 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2e110 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2e120 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2e130 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2e140 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e150 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2e160 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2e170 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2e180 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2e190 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
2e1a0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2e1b0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2e1c0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2e1d0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2e1e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2e1f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2e200 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2e210 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2e220 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2e230 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2e240 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2e250 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
2e260 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2e270 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
2e280 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
2e290 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
2e2a0 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
2e2b0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2e2c0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
2e2d0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2e2e0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2e2f0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2e300 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2e310 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
2e320 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2e330 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
2e340 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
2e350 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2e360 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
2e370 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
2e380 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
2e390 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2e3a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2e3b0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
2e3c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2e3d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2e3e0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2e3f0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2e400 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2e410 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2e420 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
2e430 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2e440 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2e450 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2e460 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2e470 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2e480 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
2e490 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
2e4a0 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
2e4b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2e4c0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2e4d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e4e0 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
2e4f0 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
2e500 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2e510 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e520 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
2e530 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
2e540 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
2e550 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2e560 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2e570 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2e580 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e590 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2e5a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2e5b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e5c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2e5d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
2e5e0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
2e5f0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
2e600 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2e610 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
2e620 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
2e630 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2e640 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
2e650 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
2e660 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
2e670 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
2e680 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2e690 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
2e6a0 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
2e6b0 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
2e6c0 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
2e6d0 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
2e6e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
2e6f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
2e700 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
2e710 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
2e720 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
2e730 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
2e740 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
2e750 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
2e760 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
2e770 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2e780 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
2e790 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2e7a0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2e7b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2e7c0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2e7d0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2e7e0 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
2e7f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
2e800 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
2e810 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2e820 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
2e830 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2e840 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2e850 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
2e860 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
2e870 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
2e880 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
2e890 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2e8a0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2e8b0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2e8c0 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
2e8d0 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
2e8e0 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
2e8f0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2e900 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2e910 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
2e920 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
2e930 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2e940 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2e950 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
2e960 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
2e970 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
2e980 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
2e990 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
2e9a0 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
2e9b0 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
2e9c0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2e9d0 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2e9e0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2e9f0 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
2ea00 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
2ea10 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2ea20 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2ea30 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
2ea40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2ea50 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2ea60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2ea70 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2ea80 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
2ea90 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
2eaa0 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
2eab0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2eac0 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
2ead0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2eae0 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
2eaf0 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
2eb00 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
2eb10 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2eb20 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2eb30 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
2eb40 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
2eb50 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
2eb60 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2eb70 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
2eb80 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
2eb90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2eba0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2ebb0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2ebc0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2ebd0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2ebe0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2ebf0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2ec00 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2ec10 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2ec20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69  Every SQL functi
2ec30 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2ec40 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74  n must be able t
2ec50 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55  o work.** with U
2ec60 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
2ec70 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
2ec80 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
2ec90 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
2eca0 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
2ecb0 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
2ecc0 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
2ecd0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2ece0 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73   may.** invoke s
2ecf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ed00 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
2ed10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ed20 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
2ed30 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
2ed40 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2ed50 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2ed60 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
2ed70 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e  extRep..** ^When
2ed80 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2ed90 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2eda0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
2edb0 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
2edc0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
2edd0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
2ede0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
2edf0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
2ee00 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
2ee10 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
2ee20 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
2ee30 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
2ee40 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
2ee50 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
2ee60 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
2ee70 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2ee80 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
2ee90 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
2eea0 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
2eeb0 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
2eec0 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
2eed0 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
2eee0 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2eef0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
2ef00 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
2ef10 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
2ef20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2ef30 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
2ef40 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
2ef50 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
2ef60 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
2ef70 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2ef80 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
2ef90 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
2efa0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
2efb0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2efc0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2efd0 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
2efe0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2eff0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2f000 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2f010 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2f020 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
2f030 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
2f040 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2f050 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2f060 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2f070 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
2f080 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2f090 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2f0a0 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
2f0b0 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
2f0c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
2f0d0 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
2f0e0 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
2f0f0 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
2f100 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
2f110 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
2f120 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  s NULL pointers 
2f130 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
2f140 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
2f150 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
2f160 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
2f170 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2f180 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2f190 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
2f1a0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
2f1b0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2f1c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2f1d0 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
2f1e0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2f1f0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
2f200 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
2f210 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
2f220 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
2f230 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
2f240 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2f250 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
2f260 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
2f270 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
2f280 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
2f290 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
2f2a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2f2b0 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
2f2c0 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
2f2d0 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
2f2e0 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
2f2f0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
2f300 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
2f310 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
2f320 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
2f330 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2f340 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
2f350 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
2f360 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2f370 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
2f380 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
2f390 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
2f3a0 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2f3b0 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2f3c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2f3d0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2f3e0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2f3f0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2f400 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2f410 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2f420 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2f430 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2f440 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2f450 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
2f460 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
2f470 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
2f480 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
2f490 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
2f4a0 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
2f4b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
2f4c0 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
2f4d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2f4e0 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
2f4f0 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
2f500 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
2f510 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2f520 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2f530 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
2f540 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
2f550 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2f560 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2f570 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
2f580 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
2f590 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
2f5a0 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
2f5b0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
2f5c0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2f5d0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2f5e0 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
2f5f0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2f600 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2f610 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
2f620 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
2f630 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
2f640 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2f650 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2f660 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2f670 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
2f680 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
2f690 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
2f6a0 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
2f6b0 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
2f6c0 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
2f6d0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f6e0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
2f6f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f700 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2f710 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
2f720 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
2f730 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
2f740 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
2f750 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
2f760 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
2f770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
2f780 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
2f790 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
2f7a0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
2f7b0 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
2f7c0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2f7d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2f7e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2f7f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2f800 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2f810 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2f820 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2f830 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2f840 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2f850 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2f860 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2f870 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2f880 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2f890 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2f8a0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2f8b0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2f8c0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2f8d0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2f8e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f8f0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2f900 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2f910 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2f920 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2f930 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2f940 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2f950 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2f960 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2f970 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2f980 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2f990 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2f9a0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2f9b0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2f9c0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2f9d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2f9e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2f9f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2fa00 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2fa10 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2fa20 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2fa30 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2fa40 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2fa50 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2fa60 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2fa70 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2fa80 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2fa90 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2faa0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fab0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2fac0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2fad0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2fae0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
2faf0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2fb00 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2fb10 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
2fb20 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
2fb30 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2fb40 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2fb50 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2fb60 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2fb70 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2fb80 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2fb90 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2fba0 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2fbb0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2fbc0 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2fbd0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2fbe0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2fbf0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2fc00 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2fc10 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2fc20 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2fc30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2fc40 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2fc50 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2fc60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fc70 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2fc80 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2fc90 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2fca0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2fcb0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2fcc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fcd0 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
2fce0 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
2fcf0 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
2fd00 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
2fd10 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
2fd20 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
2fd30 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
2fd40 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
2fd50 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
2fd60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
2fd70 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
2fd80 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
2fd90 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
2fda0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
2fdb0 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2fdc0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2fdd0 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2fde0 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2fdf0 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2fe00 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2fe10 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2fe20 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
2fe30 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
2fe40 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
2fe50 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
2fe60 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2fe70 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
2fe80 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
2fe90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
2fea0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2feb0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
2fec0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
2fed0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2fee0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2fef0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
2ff00 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2ff10 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
2ff20 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2ff30 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2ff40 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
2ff50 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
2ff60 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
2ff70 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
2ff80 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
2ff90 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2ffa0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
2ffb0 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
2ffc0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2ffd0 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
2ffe0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
2fff0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
30000 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
30010 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
30020 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a  rameter Values.*
30030 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
30040 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
30050 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
30060 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
30070 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
30080 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
30090 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
300a0 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
300b0 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
300c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
300d0 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
300e0 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
300f0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
30100 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
30110 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
30120 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
30130 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30140 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
30150 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30160 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
30170 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
30180 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
30190 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
301a0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
301b0 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
301c0 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
301d0 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
301e0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
301f0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
30200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30210 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
30220 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
30230 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
30240 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
30250 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
30260 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
30270 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
30280 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
30290 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
302a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
302b0 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
302c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
302d0 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
302e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
302f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
30300 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
30310 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
30320 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
30330 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30340 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
30350 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
30360 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
30370 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
30380 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
30390 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
303a0 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
303b0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
303c0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
303d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
303e0 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
303f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30400 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
30410 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
30420 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
30430 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
30440 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
30450 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
30460 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
30470 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
30480 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
30490 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
304a0 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
304b0 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
304c0 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
304d0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
304e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
304f0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
30500 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
30510 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
30520 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
30530 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
30540 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
30550 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
30560 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
30570 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
30580 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
30590 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
305a0 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
305b0 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
305c0 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
305d0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
305e0 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
305f0 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
30600 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
30610 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
30620 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
30630 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
30640 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
30650 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
30660 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
30670 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
30680 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
30690 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
306a0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
306b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
306c0 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
306d0 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
306e0 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
306f0 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
30700 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
30710 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
30720 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
30730 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
30740 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
30750 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
30760 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
30770 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
30780 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
30790 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
307a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
307b0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
307c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
307d0 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
307e0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
307f0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
30800 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
30810 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
30820 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
30830 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
30840 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30850 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
30860 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30870 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
30880 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
30890 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
308a0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
308b0 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
308c0 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
308d0 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
308e0 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
308f0 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
30900 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
30910 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
30920 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
30930 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
30940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30950 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
30960 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
30970 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
30980 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
30990 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
309a0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
309b0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
309c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
309d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
309e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
309f0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
30a00 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
30a10 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
30a20 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
30a30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
30a40 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
30a50 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
30a60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
30a70 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
30a80 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
30a90 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30aa0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
30ab0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30ac0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
30ad0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
30ae0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
30af0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
30b00 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
30b10 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
30b20 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
30b30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
30b40 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
30b50 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
30b60 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
30b70 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
30b80 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
30b90 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
30ba0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
30bb0 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
30bc0 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
30bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
30be0 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
30bf0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30c00 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
30c10 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
30c20 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
30c30 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
30c40 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
30c50 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
30c60 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
30c70 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
30c80 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
30c90 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
30ca0 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
30cb0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
30cc0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
30cd0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30ce0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
30cf0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
30d00 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
30d10 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
30d20 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
30d30 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
30d40 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
30d50 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
30d60 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
30d70 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
30d80 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
30d90 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
30da0 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
30db0 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
30dc0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
30dd0 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
30de0 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
30df0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
30e00 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
30e10 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
30e20 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
30e30 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
30e40 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
30e50 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
30e60 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
30e70 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
30e80 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
30e90 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30ea0 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
30eb0 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
30ec0 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
30ed0 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
30ee0 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
30ef0 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
30f00 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
30f10 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
30f20 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
30f30 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73   if N is.** less
30f40 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
30f50 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
30f60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65  emory allocate e
30f70 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
30f80 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
30f90 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
30fa0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
30fb0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
30fc0 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
30fd0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
30fe0 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
30ff0 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
31000 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
31010 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
31020 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
31030 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
31040 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
31050 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
31060 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
31070 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
31080 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
31090 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
310a0 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a  location.)^.**.*
310b0 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
310c0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
310d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
310e0 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
310f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31100 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
31110 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
31120 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
31130 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31140 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
31150 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
31160 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
31170 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
31180 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
31190 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
311a0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
311b0 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
311c0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
311d0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
311e0 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
311f0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
31200 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
31210 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
31220 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
31230 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
31240 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
31250 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
31260 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
31270 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31280 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
31290 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
312a0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
312b0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
312c0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
312d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
312e0 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
312f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
31300 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
31310 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
31320 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
31330 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
31340 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
31350 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
31360 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
31370 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
31380 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31390 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
313a0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
313b0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
313c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
313d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
313e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
313f0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
31400 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
31410 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
31420 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
31430 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31440 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
31450 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
31460 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
31470 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
31480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31490 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
314a0 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
314b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
314c0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
314d0 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
314e0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
314f0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
31500 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
31510 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
31520 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
31530 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
31540 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31550 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
31560 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31570 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
31580 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
31590 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
315a0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
315b0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
315c0 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
315d0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
315e0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
315f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
31600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31610 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
31620 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
31630 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
31640 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
31650 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
31660 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
31670 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
31680 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
31690 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
316a0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
316b0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
316c0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
316d0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
316e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
316f0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
31700 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
31710 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
31720 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
31730 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
31740 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
31750 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
31760 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
31770 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
31780 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
31790 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
317a0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
317b0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
317c0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
317d0 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
317e0 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
317f0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
31800 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
31810 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
31820 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
31830 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
31840 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
31850 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
31860 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
31870 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
31880 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
31890 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
318a0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
318b0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
318c0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
318d0 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
318e0 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
318f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
31900 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
31910 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
31920 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
31930 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
31940 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
31950 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
31960 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
31970 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
31980 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
31990 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
319a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
319b0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
319c0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
319d0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
319e0 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
319f0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
31a00 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
31a10 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
31a20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
31a30 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
31a40 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
31a50 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
31a60 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
31a70 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
31a80 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
31a90 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
31aa0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
31ab0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
31ac0 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
31ad0 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
31ae0 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
31af0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
31b00 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
31b10 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
31b20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
31b30 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31b40 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
31b50 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
31b60 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
31b70 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
31b80 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
31b90 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
31ba0 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
31bb0 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
31bc0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
31bd0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
31be0 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
31bf0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
31c00 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
31c10 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
31c20 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
31c30 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
31c40 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
31c50 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
31c60 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
31c70 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
31c80 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
31c90 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
31ca0 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
31cb0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
31cc0 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
31cd0 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
31ce0 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
31cf0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
31d00 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
31d10 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
31d20 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
31d30 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
31d40 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
31d50 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
31d60 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
31d70 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
31d80 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
31d90 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
31da0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
31db0 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
31dc0 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
31dd0 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
31de0 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
31df0 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
31e00 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
31e10 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
31e20 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
31e30 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
31e40 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
31e50 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
31e60 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
31e70 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
31e80 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
31e90 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
31ea0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31eb0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
31ec0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
31ed0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
31ee0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
31ef0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
31f00 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
31f10 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
31f20 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
31f30 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
31f40 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
31f50 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
31f60 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
31f70 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
31f80 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
31f90 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
31fa0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
31fb0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
31fc0 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
31fd0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
31fe0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
31ff0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
32000 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
32010 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
32020 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
32030 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
32040 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
32050 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
32060 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
32070 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
32080 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
32090 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
320a0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
320b0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
320c0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
320d0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
320e0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
320f0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
32100 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
32110 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
32120 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
32130 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
32140 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
32150 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
32160 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
32170 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
32180 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
32190 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
321a0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
321b0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
321c0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
321d0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
321e0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
321f0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
32200 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
32210 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
32220 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
32230 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
32240 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
32250 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
32260 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
32270 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
32280 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
32290 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
322a0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
322b0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
322c0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
322d0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
322e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
322f0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
32300 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
32310 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
32320 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
32330 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
32340 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
32350 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
32360 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
32370 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
32380 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
32390 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
323a0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
323b0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
323c0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
323d0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
323e0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
323f0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
32400 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
32410 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
32420 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32430 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
32440 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
32450 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
32460 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32470 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32480 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
32490 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
324a0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
324b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
324c0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
324d0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
324e0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
324f0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
32500 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32510 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
32520 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
32530 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
32540 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
32550 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32560 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
32570 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
32580 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
32590 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
325a0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
325b0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
325c0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
325d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
325e0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
325f0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
32600 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
32610 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
32620 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32630 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
32640 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
32650 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
32660 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
32670 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32680 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32690 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
326a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
326b0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
326c0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
326d0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
326e0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
326f0 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
32700 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
32710 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
32720 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
32730 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
32740 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
32750 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
32760 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
32770 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
32780 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
32790 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
327a0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
327b0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
327c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
327d0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
327e0 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
327f0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
32800 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
32810 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32820 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
32830 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
32840 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
32850 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
32860 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
32870 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
32880 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32890 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
328a0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
328b0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
328c0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
328d0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
328e0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
328f0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
32900 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
32910 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
32920 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32930 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
32940 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32950 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
32960 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
32970 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
32980 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
32990 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
329a0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
329b0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
329c0 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
329d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
329e0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
329f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
32a00 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
32a10 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
32a20 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
32a30 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
32a40 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
32a50 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
32a60 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
32a70 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
32a80 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
32a90 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
32aa0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
32ab0 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
32ac0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32ad0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
32ae0 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
32af0 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
32b00 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
32b10 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
32b20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
32b30 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
32b40 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
32b50 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
32b60 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
32b70 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
32b80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32b90 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
32ba0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32bb0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
32bc0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
32bd0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
32be0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
32bf0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
32c00 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
32c10 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
32c20 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
32c30 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
32c40 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
32c50 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
32c60 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
32c70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32c80 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
32c90 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
32ca0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
32cb0 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
32cc0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
32cd0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
32ce0 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
32cf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32d00 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
32d10 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
32d20 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
32d30 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
32d40 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32d50 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
32d60 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
32d70 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
32d80 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
32d90 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
32da0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
32db0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
32dc0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
32dd0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
32de0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32df0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
32e00 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
32e10 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
32e20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
32e30 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
32e40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32e50 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
32e60 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
32e70 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
32e80 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
32e90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32ea0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
32eb0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
32ec0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32ed0 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
32ee0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
32ef0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
32f00 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
32f10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32f20 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
32f30 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
32f40 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
32f50 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
32f60 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32f70 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
32f80 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
32f90 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
32fa0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
32fb0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
32fc0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
32fd0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
32fe0 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
32ff0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
33000 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
33010 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
33020 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
33030 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
33040 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
33050 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
33060 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
33070 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
33080 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
33090 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
330a0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
330b0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
330c0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
330d0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
330e0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
330f0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
33100 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
33110 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
33120 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
33130 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
33140 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33150 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
33160 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
33170 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
33180 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
33190 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
331a0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
331b0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
331c0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
331d0 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
331e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
331f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
33200 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
33210 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
33220 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
33230 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
33240 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
33250 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
33260 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
33270 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
33280 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
33290 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
332a0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
332b0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
332c0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
332d0 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
332e0 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
332f0 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
33300 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
33310 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
33320 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
33330 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
33340 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
33350 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
33360 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
33370 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
33380 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
33390 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
333a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
333b0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
333c0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
333d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
333e0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
333f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
33400 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
33410 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
33420 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
33430 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
33440 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
33450 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
33460 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
33470 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
33480 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
33490 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
334a0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
334b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
334c0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
334d0 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
334e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
334f0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
33500 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
33510 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
33520 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
33530 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
33540 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
33550 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
33560 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
33570 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
33580 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
33590 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
335a0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
335b0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
335c0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
335d0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
335e0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
335f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
33600 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
33610 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
33620 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
33630 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
33640 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
33650 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
33660 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
33670 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
33680 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
33690 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
336a0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
336b0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
336c0 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
336d0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
336e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
336f0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
33700 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
33710 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
33720 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33730 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33740 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
33750 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
33760 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33770 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
33780 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
33790 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
337a0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
337b0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
337c0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
337d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
337e0 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
337f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
33800 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
33810 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
33820 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
33830 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
33840 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
33850 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
33860 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
33870 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
33880 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
33890 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
338a0 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
338b0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
338c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
338d0 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
338e0 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
338f0 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
33900 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
33910 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
33920 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
33930 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
33940 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
33950 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
33960 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
33970 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
33980 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
33990 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
339a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
339b0 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
339c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
339d0 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
339e0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
339f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
33a00 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33a10 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
33a20 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
33a30 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
33a40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
33a50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33a60 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
33a70 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
33a80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33a90 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
33aa0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33ab0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
33ac0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33ad0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
33ae0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
33af0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
33b00 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33b10 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
33b20 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
33b30 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
33b40 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
33b50 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
33b60 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
33b70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33b80 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
33b90 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
33ba0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33bb0 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
33bc0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
33bd0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33be0 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
33bf0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
33c00 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
33c10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33c20 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
33c30 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
33c40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33c50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33c60 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
33c70 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
33c80 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
33c90 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
33ca0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33cb0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
33cc0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
33cd0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
33ce0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
33cf0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
33d00 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
33d10 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
33d20 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
33d30 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33d40 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
33d50 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
33d60 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
33d70 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
33d80 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
33d90 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
33da0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
33db0 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
33dc0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
33dd0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
33de0 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
33df0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
33e00 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
33e10 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
33e20 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
33e30 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
33e40 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
33e50 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
33e60 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
33e70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33e80 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
33e90 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
33ea0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
33eb0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
33ec0 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
33ed0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
33ee0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33ef0 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
33f00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33f10 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
33f20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
33f30 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
33f40 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
33f50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33f60 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
33f70 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
33f80 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
33f90 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
33fa0 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
33fb0 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
33fc0 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
33fd0 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
33fe0 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
33ff0 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
34000 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
34010 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
34020 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
34030 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
34040 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
34050 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
34060 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
34070 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
34080 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
34090 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
340a0 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
340b0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
340c0 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
340d0 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
340e0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
340f0 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
34100 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
34110 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
34120 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
34130 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
34140 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
34150 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
34160 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
34170 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
34180 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
34190 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
341a0 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
341b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
341c0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
341d0 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
341e0 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
341f0 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
34200 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
34210 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
34220 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
34230 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69   is an applicati
34240 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
34250 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
34260 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
34270 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
34280 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
34290 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
342a0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
342b0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
342c0 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
342d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
342e0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
342f0 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
34300 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34310 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
34320 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
34330 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
34340 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
34350 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
34360 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
34370 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
34380 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
34390 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
343a0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
343b0 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
343c0 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
343d0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
343e0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
343f0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34400 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
34410 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
34420 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
34430 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
34440 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
34450 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
34460 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
34470 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
34480 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
34490 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
344a0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
344b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
344c0 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
344d0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
344e0 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
344f0 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
34500 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
34510 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
34520 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
34530 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34540 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
34550 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
34560 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
34570 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
34580 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
34590 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
345a0 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
345b0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
345c0 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
345d0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
345e0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
345f0 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72  on must always r
34600 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
34610 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
34620 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
34630 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
34640 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34650 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
34660 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
34670 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
34680 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
34690 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
346a0 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
346b0 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
346c0 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
346d0 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
346e0 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
346f0 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
34700 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
34710 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
34720 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
34730 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
34740 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
34750 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
34760 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
34770 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
34780 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
34790 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
347a0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
347b0 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
347c0 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
347d0 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
347e0 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
347f0 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
34800 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
34810 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
34820 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
34830 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
34840 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
34850 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
34860 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
34870 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
34880 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
34890 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
348a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
348b0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
348c0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
348d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
348e0 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
348f0 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
34900 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
34910 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
34920 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
34930 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34940 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
34950 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
34960 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
34970 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
34980 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
34990 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
349a0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
349b0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
349c0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
349d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
349e0 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
349f0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
34a00 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
34a10 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
34a20 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
34a30 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
34a40 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
34a50 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34a60 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
34a70 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
34a80 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
34a90 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
34aa0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
34ab0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
34ac0 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
34ad0 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
34ae0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
34af0 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
34b00 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34b10 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
34b20 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
34b30 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
34b40 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
34b50 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
34b60 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
34b70 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
34b80 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
34b90 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
34ba0 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
34bb0 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
34bc0 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
34bd0 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
34be0 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
34bf0 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
34c00 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
34c10 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
34c20 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34c30 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
34c40 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34c50 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
34c60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34c70 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
34c80 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
34c90 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
34ca0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
34cb0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
34cc0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
34cd0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34ce0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34cf0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
34d00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34d10 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
34d20 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
34d30 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
34d40 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
34d50 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
34d60 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
34d70 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
34d80 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
34d90 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
34da0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
34db0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
34dc0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
34dd0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
34de0 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
34df0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
34e00 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
34e10 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
34e20 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
34e30 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
34e40 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
34e50 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
34e60 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
34e70 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
34e80 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
34e90 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
34ea0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
34eb0 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
34ec0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
34ed0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
34ee0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
34ef0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
34f00 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
34f10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34f20 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
34f30 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
34f40 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
34f50 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
34f60 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
34f70 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
34f80 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
34f90 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
34fa0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34fb0 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
34fc0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
34fd0 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
34fe0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
34ff0 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
35000 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
35010 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
35020 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
35030 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
35040 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
35050 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
35060 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
35070 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
35080 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
35090 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
350a0 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
350b0 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
350c0 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
350d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
350e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
350f0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
35100 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
35110 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
35120 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
35130 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
35140 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35150 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
35160 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35170 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
35180 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
35190 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
351a0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
351b0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
351c0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
351d0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
351e0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
351f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
35200 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
35210 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
35220 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
35230 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
35240 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
35250 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
35260 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
35270 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
35280 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
35290 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
352a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
352b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
352c0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
352d0 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
352e0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
352f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35300 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
35310 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35320 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
35330 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35340 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
35350 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35360 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35370 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
35380 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
35390 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
353a0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
353b0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
353c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
353d0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
353e0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
353f0 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
35400 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
35410 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
35420 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
35430 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
35440 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
35450 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
35460 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
35470 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
35480 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
35490 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
354a0 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
354b0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
354c0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
354d0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
354e0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
354f0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
35500 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
35510 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
35520 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
35530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35540 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
35550 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
35560 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
35570 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
35580 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
35590 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
355a0 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
355b0 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
355c0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
355d0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
355e0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
355f0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
35600 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
35610 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
35620 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
35630 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
35640 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
35650 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
35660 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
35670 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
35680 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
35690 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
356a0 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
356b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
356c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
356d0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
356e0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
356f0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
35700 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
35710 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
35720 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
35730 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
35740 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61  key for a SEE da
35750 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
35760 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
35770 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72  one of the SEE r
35780 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
35790 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
357a0 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
357b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
357c0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
357d0 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
357e0 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
357f0 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
35800 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
35810 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
35820 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
35830 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
35840 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
35850 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
35860 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
35870 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
35880 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
35890 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
358a0 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
358b0 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
358c0 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
358d0 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
358e0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
358f0 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
35900 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
35910 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
35920 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
35930 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61  ep() function ca
35940 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
35950 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
35960 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
35970 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
35980 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
35990 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
359a0 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
359b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
359c0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
359d0 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
359e0 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
359f0 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
35a00 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
35a10 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
35a20 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
35a30 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
35a40 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
35a50 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
35a60 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
35a70 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  eep actually.** 
35a80 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
35a90 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
35aa0 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
35ab0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69  .**.** ^SQLite i
35ac0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
35ad0 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
35ae0 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
35af0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
35b00 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
35b10 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
35b20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29   If the xSleep()
35b30 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
35b40 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
35b50 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
35b60 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e   correctly, or n
35b70 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  ot implemented a
35b80 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74  t.** all, then t
35b90 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
35ba0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d  qlite3_sleep() m
35bb0 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20  ay deviate from 
35bc0 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a  the description.
35bd0 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ** in the previo
35be0 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a  us paragraphs..*
35bf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
35c00 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
35c10 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
35c20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
35c30 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
35c40 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  Files.**.** ^(If
35c50 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
35c60 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
35c70 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
35c80 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
35c90 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
35ca0 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65  der (a.k.a. dire
35cb0 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
35cc0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
35cd0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
35ce0 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67  QLite when using
35cf0 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c   a built-in [sql
35d00 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a  ite3_vfs | VFS].
35d10 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  ** will be place
35d20 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
35d30 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73  ory.)^  ^If this
35d40 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
35d50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
35d60 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66  then SQLite perf
35d70 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f  orms a search fo
35d80 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
35d90 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
35da0 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
35db0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
35dc0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
35dd0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
35de0 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
35df0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
35e00 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
35e10 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
35e20 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
35e30 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
35e40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35e50 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
35e60 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
35e70 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
35e80 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
35e90 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
35ea0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
35eb0 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
35ec0 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
35ed0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
35ee0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
35ef0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
35f00 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
35f10 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
35f20 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
35f30 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
35f40 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
35f50 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
35f60 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  The [temp_store_
35f70 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
35f80 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
35f90 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
35fa0 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
35fb0 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
35fc0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
35fd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
35fe0 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
35ff0 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
36000 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
36010 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
36020 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
36030 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
36040 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
36050 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
36060 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
36070 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
36080 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
36090 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
360a0 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
360b0 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
360c0 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
360d0 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
360e0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
360f0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
36100 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
36110 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
36120 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
36130 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
36140 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
36150 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
36160 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
36170 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
36180 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
36190 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
361a0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ded..**.** <b>No
361b0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
361c0 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
361d0 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
361e0 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
361f0 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
36200 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  o calling [sqlit
36210 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c  e3_open] or [sql
36220 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20  ite3_open_v2].  
36230 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
36240 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
36250 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
36260 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
36270 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
36280 20 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20    Here is an.** 
36290 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74  example of how t
362a0 6f 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67 20  o do this using 
362b0 43 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69 6e  C++ with the Win
362c0 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a  dows Runtime:.**
362d0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
362e0 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52  <pre>.** LPCWSTR
362f0 20 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77 73   zPath = Windows
36300 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69  ::Storage::Appli
36310 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72  cationData::Curr
36320 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20  ent->.** &nbsp; 
36330 20 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c      TemporaryFol
36340 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28  der->Path->Data(
36350 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74 68  );.** char zPath
36360 42 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54 48  Buf&#91;MAX_PATH
36370 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65   + 1&#93;;.** me
36380 6d 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20 30  mset(zPathBuf, 0
36390 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75  , sizeof(zPathBu
363a0 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72  f));.** WideChar
363b0 54 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f 55  ToMultiByte(CP_U
363c0 54 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d  TF8, 0, zPath, -
363d0 31 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69 7a  1, zPathBuf, siz
363e0 65 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a  eof(zPathBuf),.*
363f0 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c  * &nbsp;     NUL
36400 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c  L, NULL);.** sql
36410 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
36420 6f 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  ory = sqlite3_mp
36430 72 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61 74  rintf("%s", zPat
36440 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  hBuf);.** </pre>
36450 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f  </blockquote>.*/
36460 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
36470 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
36480 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
36490 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
364a0 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
364b0 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61 73   Holding Databas
364c0 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  e Files.**.** ^(
364d0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
364e0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
364f0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
36500 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
36510 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
36520 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
36530 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
36540 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ll database file
36550 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 77  s.** specified w
36560 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70  ith a relative p
36570 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65 61  athname and crea
36580 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64 20  ted or accessed 
36590 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68 65  by.** SQLite whe
365a0 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
365b0 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69  in windows [sqli
365c0 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20 77  te3_vfs | VFS] w
365d0 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a 2a  ill be assumed.*
365e0 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76 65  * to be relative
365f0 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74 6f   to that directo
36600 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20 76  ry.)^ ^If this v
36610 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
36620 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68  L.** pointer, th
36630 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
36640 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61 62  s that all datab
36650 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69 66  ase files specif
36660 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72 65  ied.** with a re
36670 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20  lative pathname 
36680 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20  are relative to 
36690 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
366a0 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65  ctory.** for the
366b0 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20   process.  Only 
366c0 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
366d0 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68 69  makes use of thi
366e0 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69  s global.** vari
366f0 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e 6f  able; it is igno
36700 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78 20  red by the unix 
36710 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67  VFS..**.** Chang
36720 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ing the value of
36730 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 77   this variable w
36740 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65 20  hile a database 
36750 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a  connection is.**
36760 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c 74   open can result
36770 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64 61   in a corrupt da
36780 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74  tabase..**.** It
36790 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
367a0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
367b0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
367c0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
367d0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
367e0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
367f0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
36800 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
36810 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
36820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36830 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
36840 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
36850 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
36860 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
36870 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
36880 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
36890 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
368a0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
368b0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
368c0 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
368d0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
368e0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
368f0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
36900 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
36910 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
36920 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
36930 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64  r..**.** ^The [d
36940 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
36950 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
36960 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
36970 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
36980 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
36990 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
369a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
369b0 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
369c0 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64  rmore,.** the [d
369d0 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
369e0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
369f0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
36a00 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
36a10 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
36a20 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
36a30 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
36a40 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
36a50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
36a60 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
36a70 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
36a80 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
36a90 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
36aa0 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
36ab0 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
36ac0 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
36ad0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
36ae0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
36af0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
36b00 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
36b10 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
36b20 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
36b30 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
36b40 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  he use of the [d
36b50 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
36b60 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
36b70 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
36b80 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
36b90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 61  char *sqlite3_da
36ba0 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  ta_directory;../
36bb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
36bc0 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d  est For Auto-Com
36bd0 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57  mit Mode.** KEYW
36be0 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
36bf0 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54  t mode}.**.** ^T
36c00 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
36c10 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
36c20 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
36c30 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
36c40 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
36c50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36c60 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
36c70 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
36c80 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
36c90 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69  ely.  ^Autocommi
36ca0 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
36cb0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74  default..** ^Aut
36cc0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
36cd0 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
36ce0 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
36cf0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
36d00 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
36d10 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
36d20 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
36d30 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
36d40 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
36d50 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
36d60 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
36d70 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
36d80 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
36d90 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
36da0 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
36db0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
36dc0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
36dd0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
36de0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
36df0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
36e00 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
36e10 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
36e20 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
36e30 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
36e40 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
36e50 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
36e60 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
36e70 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
36e80 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
36e90 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
36ea0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
36eb0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
36ec0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
36ed0 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
36ee0 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
36ef0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
36f00 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
36f10 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
36f20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
36f30 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
36f40 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
36f50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
36f60 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
36f70 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
36f80 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
36f90 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
36fa0 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
36fb0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
36fc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
36fd0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
36fe0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
36ff0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37000 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
37010 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
37020 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
37030 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
37040 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37050 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
37060 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
37070 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
37080 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37090 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
370a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
370b0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
370c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
370d0 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
370e0 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
370f0 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
37100 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
37110 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
37120 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c  st place..*/.sql
37130 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62  ite3 *sqlite3_db
37140 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
37150 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
37160 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20  API3REF: Return 
37170 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72  The Filename For
37180 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
37190 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
371a0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c  e sqlite3_db_fil
371b0 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72  ename(D,N) inter
371c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
371d0 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65  ointer to a file
371e0 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74  name.** associat
371f0 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65  ed with database
37200 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e   N of connection
37210 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64   D.  ^The main d
37220 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
37230 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61  has the name "ma
37240 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69  in".  If there i
37250 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61  s no attached da
37260 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20  tabase N on the 
37270 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
37280 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20  ection D, or if 
37290 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20  database N is a 
372a0 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d  temporary or in-
372b0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c  memory database,
372c0 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20   then.** a NULL 
372d0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
372e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
372f0 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65  filename returne
37300 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
37310 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74  on is the output
37320 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c   of the.** xFull
37330 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20  Pathname method 
37340 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e  of the [VFS].  ^
37350 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
37360 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
37370 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c  will be an absol
37380 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76  ute pathname, ev
37390 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61  en if the filena
373a0 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70  me used.** to op
373b0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
373c0 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61  originally was a
373d0 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65   URI or relative
373e0 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f   pathname..*/.co
373f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
37400 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71  3_db_filename(sq
37410 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74  lite3 *db, const
37420 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b   char *zDbName);
37430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37440 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20 61  : Determine if a
37450 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 61   database is rea
37460 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  d-only.**.** ^Th
37470 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61  e sqlite3_db_rea
37480 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72  donly(D,N) inter
37490 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20 69  face returns 1 i
374a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 4e  f the database N
374b0 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f  .** of connectio
374c0 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79  n D is read-only
374d0 2c 20 30 20 69 66 20 69 74 20 69 73 20 72 65 61  , 0 if it is rea
374e0 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20 69  d/write, or -1 i
374f0 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68  f N is not.** th
37500 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74 61  e name of a data
37510 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69  base on connecti
37520 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  on D..*/.int sql
37530 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79  ite3_db_readonly
37540 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f  (sqlite3 *db, co
37550 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
37560 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
37570 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65  REF: Find the ne
37580 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
37590 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ement.**.** ^Thi
375a0 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
375b0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
375c0 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
375d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
375e0 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
375f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
37600 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37610 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49  ection] pDb.  ^I
37620 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a  f pStmt is NULL.
37630 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74  ** then this int
37640 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
37650 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
37660 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73  first prepared s
37670 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f  tatement.** asso
37680 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
37690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
376a0 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f  ion pDb.  ^If no
376b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
376c0 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73  ent.** satisfies
376d0 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20   the conditions 
376e0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
376f0 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
37700 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74  ..**.** The [dat
37710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37720 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61  ] pointer D in a
37730 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
37740 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
37750 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20  ,S)] must refer 
37760 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  to an open datab
37770 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
37780 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75  n and in particu
37790 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  lar must not be 
377a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
377b0 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  */.sqlite3_stmt 
377c0 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  *sqlite3_next_st
377d0 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c  mt(sqlite3 *pDb,
377e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70   sqlite3_stmt *p
377f0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
37800 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
37810 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
37820 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
37830 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
37840 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
37850 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
37860 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
37870 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
37880 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
37890 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
378a0 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c  ion is [COMMIT |
378b0 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20   committed]..** 
378c0 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
378d0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
378e0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
378f0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
37900 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
37910 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37920 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
37930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37940 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
37950 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
37960 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
37970 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
37980 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
37990 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
379a0 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20   is [ROLLBACK | 
379b0 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a  rolled back]..**
379c0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
379d0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
379e0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
379f0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
37a00 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
37a10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37a20 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
37a30 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67  en..** ^The pArg
37a40 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
37a50 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  sed through to t
37a60 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  he callback..** 
37a70 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
37a80 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
37a90 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  k function retur
37aa0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20  ns non-zero,.** 
37ab0 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
37ac0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
37ad0 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
37ae0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37af0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43  _commit_hook(D,C
37b00 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ,P) and sqlite3_
37b10 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
37b20 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  C,P) functions.*
37b30 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61  * return the P a
37b40 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
37b50 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f   previous call o
37b60 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
37b70 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  ion.** on the sa
37b80 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
37b90 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e  nection] D, or N
37ba0 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66  ULL for.** the f
37bb0 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61  irst call for ea
37bc0 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44  ch function on D
37bd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d  ..**.** The comm
37be0 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20  it and rollback 
37bf0 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61  hook callbacks a
37c00 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  re not reentrant
37c10 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
37c20 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
37c30 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
37c40 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
37c50 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
37c60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37c70 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
37c80 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
37c90 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
37ca0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
37cb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
37cc0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
37cd0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
37ce0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
37cf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
37d00 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
37d10 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
37d20 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
37d30 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
37d40 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
37d50 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69 6e  Note that runnin
37d60 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 20  g any other SQL 
37d70 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c  statements, incl
37d80 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74 61  uding SELECT sta
37d90 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d  tements,.** or m
37da0 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73  erely calling [s
37db0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
37dc0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
37dd0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d  3_step()] will m
37de0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
37df0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37e00 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
37e10 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
37e20 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
37e30 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72  .**.** ^Register
37e40 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74  ing a NULL funct
37e50 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65  ion disables the
37e60 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
37e70 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69   ^When the commi
37e80 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
37e90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
37ea0 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49  zero, the [COMMI
37eb0 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  T].** operation 
37ec0 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f  is allowed to co
37ed0 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e  ntinue normally.
37ee0 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74    ^If the commit
37ef0 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73   hook.** returns
37f00 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
37f10 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20  the [COMMIT] is 
37f20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
37f30 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20   [ROLLBACK]..** 
37f40 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  ^The rollback ho
37f50 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ok is invoked on
37f60 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74   a rollback that
37f70 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20   results from a 
37f80 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72  commit.** hook r
37f90 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72  eturning non-zer
37fa0 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f  o, just as it wo
37fb0 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20  uld be with any 
37fc0 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a  other rollback..
37fd0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
37fe0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
37ff0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
38000 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
38010 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65  ve been.** rolle
38020 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
38030 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
38040 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
38050 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
38060 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
38070 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
38080 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
38090 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54   to occur..** ^T
380a0 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
380b0 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
380c0 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
380d0 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
380e0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
380f0 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
38100 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
38110 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
38120 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
38130 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
38140 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
38150 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  face..*/.void *s
38160 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
38170 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
38180 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
38190 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
381a0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
381b0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
381c0 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
381d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
381e0 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
381f0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
38200 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
38210 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
38220 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
38230 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
38240 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
38250 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
38260 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38270 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
38280 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
38290 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
382a0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
382b0 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
382c0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
382d0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  ed..** ^Any call
382e0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
382f0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
38300 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
38310 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
38320 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38330 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
38340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
38350 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
38360 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
38370 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
38380 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
38390 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
383a0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
383b0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
383c0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
383d0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
383e0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
383f0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
38400 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
38410 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63  k()..** ^The sec
38420 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
38430 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
38440 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
38450 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
38460 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
38470 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
38480 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
38490 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
384a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
384b0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
384c0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
384d0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
384e0 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
384f0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
38500 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
38510 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
38520 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
38530 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
38540 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20  ..** ^The final 
38550 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
38560 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
38570 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
38580 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66   ^In the case of
38590 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
385a0 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
385b0 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
385c0 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
385d0 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65  .** ^(The update
385e0 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
385f0 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
38600 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
38610 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
38620 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
38630 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
38640 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a  sequence).)^.**.
38650 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65  ** ^In the curre
38660 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
38670 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
38680 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
38690 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
386a0 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
386b0 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
386c0 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
386d0 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
386e0 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
386f0 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65  se.  ^Nor is the
38700 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
38710 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
38720 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
38730 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
38740 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
38750 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
38760 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
38770 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
38780 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
38790 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
387a0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
387b0 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
387c0 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
387d0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
387e0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
387f0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
38800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38810 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
38820 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
38830 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
38840 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
38850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38860 6e