/ Hex Artifact Content
Login

Artifact 84cd7be33f5bf39329e018f93eb34b4a345c9c23:


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 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
31c0: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
31d0: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
31e0: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
31f0: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3200: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3210: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3220: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3230: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3240: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3250: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
3260: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
3270: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
3280: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
3290: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
32a0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
32b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
32c0: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
32e0: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
32f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3300: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3310: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3320: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3330: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3350: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3360: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
3370: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
3380: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
3390: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
33a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
33c0: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
33d0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
33e0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
33f0: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3400: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3410: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3420: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3430: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3440: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3450: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
3460: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3470: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
3480: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
3490: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
34a0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
34b0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
34c0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
34d0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34e0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
34f0: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3500: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3520: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3530: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
3540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
3550: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
3560: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
3570: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3580: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3590: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
35a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
35b0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
35d0: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
35e0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
35f0: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3600: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3610: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3620: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3630: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3640: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3650: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3660: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3670: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3680: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3690: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
36a0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
36b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
36c0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
36d0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
36e0: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
36f0: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3710: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3720: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3730: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3740: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3750: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3760: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3770: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3780: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3790: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
37a0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
37b0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
37c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
37d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
37e0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
37f0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3800: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3810: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3820: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3830: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3840: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3850: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3860: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3870: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3880: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3890: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
38a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38b0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
38c0: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
38d0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
38e0: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
38f0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3900: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3910: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3920: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3930: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3940: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3950: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3960: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3970: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3980: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3990: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
39a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
39b0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
39c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
39e0: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
39f0: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3a00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3a10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3a20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3a30: 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65   close [database
3a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
3a50: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
3a60: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
3a90: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
3aa0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
3ab0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3ac0: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
3ad0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3ae0: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
3af0: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
3b00: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
3b10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3b20: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3b30: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3b40: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
3b60: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
3b90: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
3ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
3bb0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3bd0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
3be0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
3bf0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3c00: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3c10: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3c20: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3c30: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
3c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3c70: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
3c80: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3cb0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3cc0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3cd0: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3ce0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
3cf0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
3d00: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
3d10: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
3d20: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
3d30: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
3d40: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
3d50: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
3d60: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
3d70: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
3d80: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
3d90: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
3da0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
3db0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
3dc0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
3dd0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
3de0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
3df0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
3e00: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
3e10: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
3e20: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
3e30: 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20  sult codes],.** 
3e40: 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
3e50: 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51  _conflict()] [SQ
3e60: 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
3e70: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a  result codes]..*
3e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e90: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3ea0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3eb0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3ec0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3ed0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ee0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3ef0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3f00: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3f10: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3f30: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f40: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f50: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f70: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f80: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f90: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fb0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3fc0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3fd0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fe0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3ff0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4000: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4010: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4020: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4040: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4050: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4060: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4070: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4080: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4090: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
40a0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
40b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
40c0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
40d0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40e0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40f0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4100: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4110: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4120: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4130: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4140: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4150: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4160: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4170: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4180: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4190: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
41a0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
41b0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
41c0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
41d0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41f0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4200: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4210: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4220: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4240: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4250: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4260: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4270: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4290: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
42a0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
42b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
42c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42d0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42e0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42f0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4300: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4310: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4320: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4330: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4350: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4360: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4370: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4380: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4390: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
43a0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
43b0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
43c0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
43d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43e0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43f0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4400: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4420: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4430: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4440: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4450: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4460: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4470: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4480: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
44a0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
44b0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
44c0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
44d0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44e0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44f0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4500: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4510: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4520: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4530: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4540: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4550: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4560: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4570: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4580: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4590: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
45a0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
45b0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
45c0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
45d0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45e0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45f0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4600: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4610: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4620: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4630: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4650: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4660: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4670: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4680: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4690: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
46a0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
46b0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
46c0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
46d0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46e0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4700: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4710: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4720: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4730: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4740: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4750: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4760: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4770: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4780: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4790: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
47a0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
47b0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
47c0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
47d0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47e0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47f0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4800: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4810: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4820: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4830: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4840: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4850: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4860: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4870: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4880: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4890: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
48a0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
48b0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
48c0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
48d0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48e0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48f0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4900: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4910: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4920: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4930: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4940: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4950: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4960: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4970: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4980: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4990: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
49a0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
49b0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
49c0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
49d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49e0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49f0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4a00: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4a10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4a20: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4a30: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a40: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a50: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a70: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a80: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a90: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4aa0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4ab0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4ac0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4ad0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4ae0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4af0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4b00: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b20: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4b30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b40: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b60: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b80: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ba0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4bb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4bc0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4be0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4c00: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4c20: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4c30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c40: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c60: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c80: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ca0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4cb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4cc0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ce0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4d00: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4d10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4d20: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4d30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d40: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d60: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4da0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4de0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4e20: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e60: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4ea0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ee0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4f20: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fe0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4ff0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5000: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5010: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5020: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5030: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5040: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5050: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5060: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5070: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5080: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
50a0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
50b0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
50c0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
50d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
50e0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
50f0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5100: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5110: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5120: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5130: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5140: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
5160: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5170: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5180: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
51a0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
51b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
51c0: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
51d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
51e0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
51f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5200: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5210: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5220: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5230: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5240: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5250: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5260: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5270: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5280: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5290: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
52a0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
52b0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
52c0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
52d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
52e0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
52f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5300: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5310: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5320: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5330: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5350: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5360: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5370: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5380: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53a0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
53b0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
53c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
53d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53f0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5400: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5410: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5430: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5440: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5470: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
5480: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
5490: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
54a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
54b0: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
54c0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
54d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
54e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5500: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
5510: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
5520: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5540: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5550: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
5560: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5580: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
5590: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
55a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
55c0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
55d0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
55e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5600: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
5610: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
5620: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5640: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
5650: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
5660: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5680: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
5690: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
56a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
56b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
56c0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
56d0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
56e0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
56f0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5710: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
5720: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
5730: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5740: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5760: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5770: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
5780: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5790: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
57b0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
57c0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
57d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
57e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5800: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
5810: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
5820: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
5830: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
5860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5870: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5880: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5890: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
58a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
58b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
58c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
58d0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
58e0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
58f0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
5900: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
5910: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5920: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5930: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5940: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5950: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5960: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5980: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5990: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
59a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
59b0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
59c0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
59d0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
59e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
59f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5a00: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5a10: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5a20: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5a30: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5a40: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5a50: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5a60: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5a70: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5a80: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5a90: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5ab0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5ac0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5ad0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
5ae0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
5af0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
5b00: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
5b10: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5b20: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5b30: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5b40: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5b50: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5b60: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5b70: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5b80: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5b90: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5ba0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5bb0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5bc0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5bd0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5be0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5c20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
5c30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5c40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5c50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5c70: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5c90: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5ca0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5cc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5cd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5ce0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5d00: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5d10: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5d30: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d50: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5d70: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
5d80: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5da0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5dc0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5dd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5de0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
5df0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5e10: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
5e20: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
5e50: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
5e60: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000800../*.** C
5e70: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5e80: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
5e90: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5ea0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5eb0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ec0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5ed0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5ee0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5ef0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5f00: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5f10: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5f20: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5f30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5f40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5f50: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5f60: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5f70: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5f90: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5fc0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5fd0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5fe0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5ff0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6000: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6010: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6020: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6030: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6040: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6060: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6070: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6080: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6090: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
60a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
60b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
60c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
60d0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
60e0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
60f0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6100: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6110: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6120: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6130: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6140: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6150: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6160: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6170: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6180: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6190: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
61a0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
61b0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
61c0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
61d0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
61e0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
61f0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6200: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6210: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6220: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6230: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6240: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6250: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6260: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6280: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6290: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62a0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
62b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62c0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
62d0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
62e0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
62f0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6300: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6310: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6320: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6330: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6340: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6350: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6360: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6370: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6380: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
6390: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
63a0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
63b0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
63c0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
63d0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
63e0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
63f0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
6400: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
6410: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
6420: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
6430: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
6440: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
6450: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
6460: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
6470: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6480: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
6490: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
64a0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
64b0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
64c0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
64d0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
64e0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
64f0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6510: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6520: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6530: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6540: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6550: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
6560: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6570: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
6580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6590: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
65a0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
65b0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
65c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
65d0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
65e0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
65f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6600: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6610: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6620: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6640: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6650: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
6660: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
6670: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
6680: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
6690: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
66a0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
66b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
66c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
66d0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
66e0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
66f0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6700: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6710: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6720: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6730: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6740: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6750: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
6760: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
6770: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
6780: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
6790: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
67a0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
67b0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
67c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
67d0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
67e0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
67f0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6800: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6810: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6820: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
6830: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6840: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6850: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
6860: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
6870: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
6880: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6890: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
68a0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
68b0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
68c0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
68d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
68e0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
68f0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6900: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6910: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6920: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6930: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6940: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6950: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
6960: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6970: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
6980: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6990: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
69a0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
69b0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
69c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
69d0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
69e0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
69f0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
6a00: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6a10: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6a20: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6a30: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6a40: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6a50: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6a60: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
6a70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
6a80: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
6a90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6aa0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
6ab0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6ac0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
6ad0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
6ae0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6af0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6b00: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6b10: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
6b20: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
6b30: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
6b40: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6b50: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6b60: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6b70: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
6b80: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6b90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6ba0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6bb0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6bc0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6bd0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6be0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6bf0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6c00: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6c10: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
6c20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6c30: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
6c40: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6c50: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6c60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6c70: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6c80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6c90: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6cb0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6cc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6cd0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6ce0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6cf0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6d00: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6d10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6d20: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6d30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6d40: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6d50: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6d60: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6d70: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6d80: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6d90: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6da0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6db0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6dc0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6dd0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6de0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6df0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6e00: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6e10: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6e20: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6e30: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6e40: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6e50: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
6e60: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
6e70: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
6e80: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
6e90: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6ea0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6eb0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6ec0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
6ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6ee0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
6ef0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
6f00: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
6f10: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
6f20: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
6f30: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
6f40: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
6f50: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
6f60: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
6f70: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
6f80: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
6f90: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
6fa0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
6fb0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
6fc0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
6fd0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
6fe0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
6ff0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7000: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7010: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7020: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7030: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7040: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7050: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7060: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7070: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7080: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7090: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
70a0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
70b0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
70c0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
70d0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
70e0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
70f0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
7100: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
7110: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7120: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7130: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7140: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7150: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7160: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7170: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7180: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7190: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
71a0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
71b0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
71c0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
71d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
71e0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
71f0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7200: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7210: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7220: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7230: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7240: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7250: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7260: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7270: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7280: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7290: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
72a0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
72b0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
72c0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
72d0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
72e0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
72f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7300: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7310: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7320: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7330: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7340: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7350: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7360: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7370: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7380: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73a0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
73b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73c0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
73d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73e0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
73f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7400: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
7410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7420: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
7430: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7440: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
7450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7460: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7470: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7480: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
7490: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
74a0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
74b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
74c0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
74d0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
74e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
74f0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
7500: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
7510: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
7520: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
7530: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7540: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
7550: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7560: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7570: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7580: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7590: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
75a0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
75b0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
75c0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
75d0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
75e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
75f0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
7600: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
7610: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
7620: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
7630: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
7640: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
7650: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7660: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7670: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7680: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
7690: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
76a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
76b0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
76c0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
76d0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
76e0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
76f0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
7700: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
7710: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
7720: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
7730: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
7740: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
7750: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
7760: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
7770: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
7780: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
7790: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
77a0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
77b0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
77c0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
77d0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
77e0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
77f0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
7800: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
7810: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
7820: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
7830: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7840: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
7850: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7860: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7870: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7880: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7890: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
78a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
78b0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
78d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
78e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
78f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
7900: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7910: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
7920: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7930: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7940: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7960: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7970: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7980: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7990: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
79a0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
79b0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
79c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
79d0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
79e0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
79f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
7a00: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
7a10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7a20: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7a30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7a50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7a60: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7a70: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7a80: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7a90: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7aa0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7ab0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7ac0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7ad0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
7ae0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
7af0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7b00: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7b10: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
7b20: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7b30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7b40: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
7b50: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
7b60: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
7b70: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
7b90: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
7ba0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
7bb0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
7bc0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7bd0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
7be0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7bf0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
7c00: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7c10: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7c20: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a  ersion 2 */.  /*
7c30: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
7c40: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
7c50: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
7c60: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
7c70: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
7c80: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
7c90: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
7ca0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
7cb0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
7cc0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
7cd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
7ce0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
7cf0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7d00: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
7d10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7d20: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
7d30: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
7d40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7d50: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
7d60: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
7d70: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
7d80: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
7d90: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7da0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
7db0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
7dc0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
7dd0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
7de0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
7df0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7e00: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
7e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
7e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7e30: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
7e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7e50: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
7e60: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
7e70: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
7e80: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
7e90: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
7ea0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
7eb0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
7ec0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
7ed0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
7ee0: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
7ef0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7f00: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
7f10: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
7f20: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
7f30: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
7f40: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
7f50: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
7f60: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
7f70: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
7f80: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
7f90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
7fa0: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
7fb0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
7fc0: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
7fd0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
7fe0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
7ff0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8000: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8010: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8020: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8030: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8040: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8050: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8060: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8070: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8080: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8090: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
80a0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
80b0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
80c0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
80d0: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
80e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
80f0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
8100: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
8110: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
8120: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
8130: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
8140: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
8150: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
8160: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
8170: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
8180: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
8190: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
81a0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
81b0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
81c0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
81d0: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
81e0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
81f0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
8200: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
8210: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
8220: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
8230: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
8240: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
8250: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ms..**.** The [S
8260: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8270: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8280: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8290: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
82a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
82b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
82c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
82d0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
82e0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
82f0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
8300: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8310: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
8320: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
8330: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
8340: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .**.** ^(The [SQ
8350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
8360: 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20  OMITTED] opcode 
8370: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
8380: 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51  ernally by.** SQ
8390: 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f  Lite and sent to
83a0: 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c   all VFSes in pl
83b0: 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f  ace of a call to
83c0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
83d0: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61  d.** when the da
83e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
83f0: 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79  n has [PRAGMA sy
8400: 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74  nchronous] set t
8410: 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65  o OFF.)^.** Some
8420: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8430: 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  es need this sig
8440: 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nal in order to 
8450: 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c  operate correctl
8460: 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d  y.** when [PRAGM
8470: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
8480: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8490: 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20  us=OFF] is set, 
84a0: 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53  but most .** VFS
84b0: 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  es do not need t
84c0: 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73  his signal and s
84d0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
84e0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
84f0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
8500: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
8510: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
8520: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
8530: 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   this.** opcode 
8540: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
8550: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
8560: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
8570: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  cialized VFSes.*
8580: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8590: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  e it.  .**.** ^T
85a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
85b0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
85c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
85d0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
85e0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
85f0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
8600: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
8610: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
8620: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
8630: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
8640: 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 74   order to work t
8650: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
8660: 6e 65 73 73 20 61 67 61 69 6e 73 74 0a 2a 2a 20  ness against.** 
8670: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
8680: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
8690: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
86a0: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
86b0: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
86c0: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
86d0: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
86e0: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
86f0: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
8700: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
8710: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
8720: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
8730: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
8740: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
8750: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
8760: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
8770: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
8780: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
8790: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
87a0: 20 74 68 6f 73 65 20 74 6f 20 76 61 6c 75 65 73   those to values
87b0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
87c0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
87d0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
87e0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
87f0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
8800: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
8810: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8820: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
8830: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
8840: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
8850: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
8860: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
8870: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
8880: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
8890: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
88a0: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
88b0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
88c0: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
88d0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
88e0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
88f0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
8900: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
8910: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
8920: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
8930: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
8940: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
8950: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
8960: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
8970: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
8980: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
8990: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
89a0: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
89b0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
89c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
89d0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
89e0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
89f0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
8a00: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
8a10: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
8a20: 69 74 65 20 41 48 65 61 64 20 4c 6f 67 5d 20 73  ite AHead Log] s
8a30: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
8a40: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
8a50: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
8a60: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
8a70: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
8a80: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
8a90: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
8aa0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
8ab0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
8ac0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
8ad0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
8ae0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
8af0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
8b00: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
8b10: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
8b20: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
8b30: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
8b40: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
8b50: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
8b60: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
8b70: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
8b80: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
8b90: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
8ba0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
8bb0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8bc0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
8bd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8be0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
8bf0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
8c00: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
8c10: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
8c20: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
8c30: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
8c40: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
8c50: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
8c60: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8c70: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
8c80: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
8c90: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
8ca0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
8cb0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
8cc0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
8cd0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
8ce0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
8cf0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
8d00: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
8d10: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
8d20: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
8d30: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
8d40: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
8d50: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
8d60: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
8d70: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
8d80: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
8d90: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
8da0: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
8db0: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
8dc0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
8dd0: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
8de0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
8df0: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
8e00: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
8e10: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
8e20: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
8e30: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
8e40: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
8e50: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
8e60: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
8e70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
8e80: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
8e90: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
8ea0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
8eb0: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
8ec0: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
8ed0: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
8ee0: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
8ef0: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
8f00: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
8f10: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
8f20: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
8f30: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
8f40: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
8f50: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
8f60: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
8f70: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
8f80: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
8f90: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
8fa0: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
8fb0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8fc0: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
8fd0: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
8fe0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
8ff0: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
9000: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
9010: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
9020: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
9030: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
9040: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
9050: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
9060: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
9070: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
9080: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
9090: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
90a0: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
90b0: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
90c0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
90d0: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
90e0: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
90f0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
9100: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
9110: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
9120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9130: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
9140: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
9150: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
9160: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
9170: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
9180: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
9190: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
91a0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
91b0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
91c0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
91d0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
91e0: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
91f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
9200: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
9210: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
9220: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9230: 54 45 52 20 20 20 20 20 37 0a 23 64 65 66 69 6e  TER     7.#defin
9240: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
9250: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
9260: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
9270: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9280: 52 45 54 52 59 20 20 20 39 0a 23 64 65 66 69 6e  RETRY   9.#defin
9290: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
92a0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 31  ERSIST_WAL     1
92b0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
92c0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
92d0: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
92e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
92f0: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 31  FSNAME         1
9300: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  2../*.** CAPI3RE
9310: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
9320: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
9330: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
9340: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
9350: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
9360: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
9370: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
9380: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
9390: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
93a0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
93b0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
93c0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
93d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
93e0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
93f0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
9400: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9410: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
9420: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
9430: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
9440: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
9450: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
9460: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
9470: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
9480: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
9490: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
94a0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
94b0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
94c0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
94d0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
94e0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
94f0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
9500: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
9510: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
9520: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
9530: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
9540: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
9550: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
9560: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
9570: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
9580: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
9590: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
95a0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
95b0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
95c0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
95d0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
95e0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
95f0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
9600: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
9610: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
9620: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
9630: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
9640: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
9650: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
9660: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
9670: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
9680: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
9690: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
96a0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
96b0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
96c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
96d0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
96e0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
96f0: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
9700: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
9710: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
9720: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
9730: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
9740: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
9750: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
9760: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
9770: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
9780: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
9790: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
97a0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
97b0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
97c0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
97d0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
97e0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
97f0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
9800: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
9810: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
9820: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
9830: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
9840: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
9850: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
9860: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
9870: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
9880: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
9890: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
98a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
98b0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
98c0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
98d0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
98e0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
98f0: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
9900: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
9910: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
9920: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
9930: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
9940: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
9950: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
9960: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
9970: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
9980: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
9990: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
99a0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
99b0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
99c0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
99d0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
99e0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
99f0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
9a00: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
9a10: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
9a20: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
9a30: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
9a40: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
9a50: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
9a60: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
9a70: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
9a80: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
9a90: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
9aa0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
9ab0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
9ac0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
9ad0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
9ae0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
9af0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
9b00: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
9b10: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
9b20: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
9b30: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
9b40: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
9b50: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
9b60: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
9b70: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
9b80: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
9b90: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
9ba0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
9bb0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
9bc0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
9bd0: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
9be0: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
9bf0: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
9c00: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
9c10: 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   10 alphanumeric
9c20: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
9c30: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
9c40: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
9c50: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
9c60: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
9c70: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
9c80: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
9c90: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
9ca0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
9cb0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
9cc0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
9cd0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
9ce0: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
9cf0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
9d00: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
9d10: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
9d20: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
9d30: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
9d40: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
9d50: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
9d60: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
9d70: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
9d80: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
9d90: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
9da0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
9db0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
9dc0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
9dd0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
9de0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
9df0: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
9e00: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
9e10: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
9e20: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
9e30: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
9e40: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
9e50: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
9e60: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
9e70: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
9e80: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
9e90: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
9ea0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
9eb0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
9ec0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
9ed0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
9ee0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
9ef0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
9f00: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
9f10: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
9f20: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
9f30: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
9f40: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
9f50: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
9f60: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
9f70: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
9f80: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
9f90: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
9fa0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
9fb0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
9fc0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
9fd0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
9fe0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
9ff0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
a000: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
a010: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
a020: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
a030: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
a040: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
a050: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
a060: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
a070: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
a080: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
a090: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
a0a0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
a0b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
a0c0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
a0d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
a0e0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
a0f0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
a100: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
a110: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
a120: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
a130: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
a140: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
a150: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
a160: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
a170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
a180: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
a190: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
a1a0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
a1b0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
a1c0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
a1d0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
a1e0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
a1f0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
a200: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
a210: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
a220: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
a230: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
a240: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
a250: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
a260: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
a270: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
a280: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
a290: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
a2a0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
a2b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
a2c0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
a2d0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
a2e0: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
a2f0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
a300: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
a310: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
a320: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
a330: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
a340: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
a350: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
a360: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
a370: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
a380: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
a390: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
a3a0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
a3b0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
a3c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
a3d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
a3e0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
a3f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
a400: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
a410: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
a420: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
a430: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
a440: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
a450: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
a460: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
a470: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
a480: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
a490: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
a4a0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
a4b0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
a4c0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
a4d0: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
a4e0: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
a4f0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
a500: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
a510: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
a520: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
a530: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
a540: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
a550: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
a560: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
a570: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
a580: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
a590: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
a5a0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
a5b0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
a5c0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
a5d0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
a5e0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
a5f0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
a600: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
a610: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
a620: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
a630: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
a640: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
a650: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
a660: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
a670: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
a680: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
a690: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
a6a0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
a6b0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
a6c0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
a6d0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
a6e0: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
a6f0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
a700: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
a710: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
a720: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
a730: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
a740: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
a750: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
a760: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
a770: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
a780: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
a790: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
a7a0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
a7b0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
a7c0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
a7d0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
a7e0: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
a7f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
a800: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
a810: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
a820: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
a830: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
a840: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
a850: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
a860: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
a870: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
a880: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
a890: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
a8a0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
a8b0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
a8c0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
a8d0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
a8e0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
a8f0: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
a900: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
a910: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
a920: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
a930: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
a940: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
a950: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
a960: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
a970: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
a980: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
a990: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
a9a0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
a9b0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
a9c0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
a9d0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
a9e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
a9f0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
aa00: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
aa10: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
aa20: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
aa30: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
aa40: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
aa50: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
aa60: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
aa70: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
aa80: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
aa90: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
aaa0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
aab0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
aac0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
aad0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
aae0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
aaf0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
ab00: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
ab10: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
ab20: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
ab30: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
ab40: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
ab50: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
ab60: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
ab70: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
ab80: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
ab90: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
aba0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
abb0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
abc0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
abd0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
abe0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
abf0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
ac00: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
ac10: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
ac20: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
ac30: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
ac40: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
ac50: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
ac60: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
ac70: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
ac80: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
ac90: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
aca0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
acb0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
acc0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
acd0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
ace0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
acf0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
ad00: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
ad10: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
ad20: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
ad30: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
ad40: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
ad50: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
ad60: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
ad70: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
ad80: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
ad90: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
ada0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
adb0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
adc0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
add0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
ade0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
adf0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
ae00: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
ae10: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
ae20: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
ae30: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
ae40: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
ae50: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
ae60: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
ae70: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
ae80: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
ae90: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
aea0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
aeb0: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
aec0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
aed0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
aee0: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
aef0: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
af00: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
af10: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
af20: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
af30: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
af40: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
af50: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
af60: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
af70: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
af80: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
af90: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
afa0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
afb0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
afc0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
afd0: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
afe0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
aff0: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
b000: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
b010: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
b020: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
b030: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
b040: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
b050: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
b060: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
b070: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
b080: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
b090: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
b0a0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
b0b0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
b0c0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
b0d0: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
b0e0: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
b0f0: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
b100: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
b110: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
b120: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
b130: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
b140: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
b150: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
b160: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
b170: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
b180: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
b190: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
b1a0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
b1b0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
b1c0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
b1d0: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
b1e0: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
b1f0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
b200: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
b210: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
b220: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
b230: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
b240: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
b250: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
b260: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
b270: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
b280: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
b290: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
b2a0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
b2b0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
b2c0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
b2d0: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
b2e0: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
b2f0: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
b300: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
b310: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
b320: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
b330: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
b340: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
b350: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
b360: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
b370: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
b380: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
b390: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
b3a0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
b3b0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
b3c0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
b3d0: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
b3e0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
b3f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
b400: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
b410: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
b420: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
b430: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
b440: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
b450: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
b460: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
b470: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
b480: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
b490: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
b4a0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
b4b0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
b4c0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
b4d0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
b4e0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
b4f0: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
b500: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
b510: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
b520: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
b530: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
b540: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
b550: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
b560: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
b570: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
b580: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
b590: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
b5a0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
b5b0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
b5c0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
b5d0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
b5e0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
b5f0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
b600: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
b610: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
b620: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
b630: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
b640: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
b650: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
b660: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
b670: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
b680: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
b690: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
b6a0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
b6b0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
b6c0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
b6d0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
b6e0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
b6f0: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
b700: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
b710: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
b720: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
b730: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
b740: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
b750: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
b760: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
b770: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
b780: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
b790: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
b7a0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
b7b0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
b7c0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
b7d0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
b7e0: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
b7f0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
b800: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
b810: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
b820: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
b830: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
b840: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
b850: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
b860: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
b870: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
b880: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
b890: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
b8a0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
b8b0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
b8c0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
b8d0: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
b8e0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
b8f0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
b900: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
b910: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
b920: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
b930: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
b940: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
b950: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
b960: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
b970: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
b980: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b990: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
b9a0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
b9b0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
b9c0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
b9d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b9e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
b9f0: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
ba00: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
ba10: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
ba20: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ba30: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
ba40: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ba50: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
ba60: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
ba70: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
ba80: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
ba90: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
baa0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
bab0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
bac0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
bad0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
bae0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
baf0: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
bb00: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
bb10: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
bb20: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
bb30: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
bb40: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
bb50: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
bb60: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
bb70: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
bb80: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
bb90: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
bba0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
bbb0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
bbc0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
bbd0: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
bbe0: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
bbf0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
bc00: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
bc10: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
bc20: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
bc30: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
bc40: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
bc50: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
bc60: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
bc70: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
bc80: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
bc90: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
bca0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
bcb0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
bcc0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
bcd0: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
bce0: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
bcf0: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
bd00: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
bd10: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
bd20: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
bd30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
bd40: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
bd50: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
bd60: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
bd70: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
bd80: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
bd90: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
bda0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
bdb0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
bdc0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
bdd0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
bde0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
bdf0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
be00: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
be10: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
be20: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
be30: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
be40: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
be50: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
be60: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
be70: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
be80: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
be90: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
bea0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
beb0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
bec0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
bed0: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
bee0: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
bef0: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
bf00: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
bf10: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
bf20: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
bf30: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
bf40: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
bf50: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
bf60: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
bf70: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
bf80: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
bf90: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
bfa0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
bfb0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
bfc0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
bfd0: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
bfe0: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
bff0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
c000: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
c010: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
c020: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
c030: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
c040: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
c050: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
c060: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
c070: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
c080: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
c090: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
c0a0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
c0b0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
c0c0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
c0d0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
c0e0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
c0f0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
c100: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
c110: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
c120: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
c130: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
c140: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
c150: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
c160: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
c170: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
c180: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
c190: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
c1a0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
c1b0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
c1c0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
c1d0: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
c1e0: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
c1f0: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
c200: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
c210: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
c220: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
c230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
c240: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
c250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c260: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
c270: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
c280: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
c290: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
c2a0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
c2b0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
c2c0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
c2d0: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
c2e0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
c2f0: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
c300: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
c310: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
c320: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
c330: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
c340: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
c350: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
c360: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
c370: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
c380: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
c390: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
c3a0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
c3b0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
c3c0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
c3d0: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
c3e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
c3f0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
c400: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
c410: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
c420: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
c430: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
c440: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
c450: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
c460: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c470: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
c480: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
c490: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
c4a0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
c4b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c4c0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
c4d0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
c4e0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
c4f0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
c500: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
c510: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
c520: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
c530: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
c540: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
c550: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
c560: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
c570: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
c580: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
c590: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
c5a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
c5b0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
c5c0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
c5d0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
c5e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
c5f0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
c600: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
c610: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
c620: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
c630: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
c640: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
c650: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
c660: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
c670: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
c680: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
c690: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
c6a0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
c6b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c6c0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
c6d0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
c6e0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
c6f0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
c700: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
c710: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
c720: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
c730: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
c740: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
c750: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
c760: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c770: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
c780: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
c790: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
c7a0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
c7b0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
c7c0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
c7d0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
c7e0: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
c7f0: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
c800: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
c810: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
c820: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
c830: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
c840: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
c850: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
c860: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
c870: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
c880: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
c890: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
c8a0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
c8b0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
c8c0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
c8d0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
c8e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c8f0: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
c900: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
c910: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
c920: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
c930: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
c940: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
c950: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c960: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
c970: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
c980: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c990: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
c9a0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
c9b0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
c9c0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
c9d0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
c9e0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
c9f0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
ca00: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ca10: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
ca20: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
ca30: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
ca40: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
ca50: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
ca60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
ca70: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
ca80: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
ca90: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
caa0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
cab0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
cac0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
cad0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
cae0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
caf0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
cb00: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
cb10: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
cb20: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
cb30: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
cb40: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
cb50: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
cb60: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
cb70: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
cb80: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
cb90: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
cba0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
cbb0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
cbc0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
cbd0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
cbe0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
cbf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
cc00: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
cc10: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
cc20: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
cc30: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
cc40: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
cc50: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
cc60: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
cc70: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
cc80: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
cc90: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
cca0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
ccb0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
ccc0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
ccd0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
cce0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
ccf0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
cd00: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
cd10: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
cd20: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
cd30: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
cd40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
cd50: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
cd60: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
cd70: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
cd80: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
cd90: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
cda0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
cdb0: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
cdc0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
cdd0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
cde0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
cdf0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
ce00: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
ce10: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
ce20: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
ce30: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
ce40: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
ce50: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
ce60: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
ce70: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
ce80: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
ce90: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
cea0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
ceb0: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
cec0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
ced0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
cee0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
cef0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
cf00: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
cf10: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
cf20: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
cf30: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
cf40: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
cf50: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
cf60: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
cf70: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
cf80: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
cf90: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
cfa0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
cfb0: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
cfc0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
cfd0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
cfe0: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
cff0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
d000: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
d010: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
d020: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
d030: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
d040: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
d050: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
d060: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
d070: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
d080: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
d090: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
d0a0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
d0b0: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
d0c0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
d0d0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
d0e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
d0f0: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
d100: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
d110: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
d120: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
d130: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
d140: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
d150: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
d160: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
d170: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
d180: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
d190: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
d1a0: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
d1b0: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
d1c0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
d1d0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
d1e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d1f0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
d200: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
d210: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
d220: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
d230: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
d240: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
d250: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
d260: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
d270: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
d280: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
d290: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
d2a0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
d2b0: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
d2c0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
d2d0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
d2e0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
d2f0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
d300: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
d310: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
d320: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
d330: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
d340: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
d350: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
d360: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
d370: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
d380: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
d390: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
d3a0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
d3b0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
d3c0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
d3d0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
d3e0: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
d3f0: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
d400: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
d410: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
d420: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
d430: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
d440: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
d450: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
d460: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
d470: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
d480: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
d490: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
d4a0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
d4b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
d4c0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
d4d0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
d4e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
d4f0: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
d500: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
d510: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
d520: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
d530: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
d540: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
d550: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
d560: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
d570: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
d580: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
d590: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
d5a0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
d5b0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
d5c0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
d5d0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
d5e0: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
d5f0: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
d600: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
d610: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
d620: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
d630: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
d640: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
d650: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
d660: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
d670: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
d680: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
d690: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
d6a0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
d6b0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
d6c0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
d6d0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
d6e0: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
d6f0: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
d700: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
d710: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
d720: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
d730: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
d740: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
d750: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
d760: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d770: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
d780: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
d790: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
d7a0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
d7b0: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
d7c0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
d7d0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
d7e0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
d7f0: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
d800: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
d810: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
d820: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
d830: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
d840: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
d850: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
d860: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
d870: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
d880: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
d890: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
d8a0: 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
d8b0: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
d8c0: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
d8d0: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
d8e0: 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
d8f0: 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
d900: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
d910: 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
d920: 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
d930: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
d940: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
d950: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
d960: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
d970: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
d980: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
d990: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
d9a0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
d9b0: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
d9c0: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
d9d0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
d9e0: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
d9f0: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
da00: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
da10: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
da20: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
da30: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
da40: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
da50: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
da60: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
da70: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
da80: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
da90: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
daa0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
dab0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
dac0: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
dad0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
dae0: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
daf0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
db00: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
db10: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
db20: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
db30: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
db40: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
db50: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
db60: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
db70: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
db80: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
db90: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
dba0: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
dbb0: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
dbc0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
dbd0: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
dbe0: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
dbf0: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
dc00: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
dc10: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
dc20: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
dc30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
dc40: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
dc50: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
dc60: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
dc70: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
dc80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
dc90: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
dca0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
dcb0: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
dcc0: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
dcd0: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
dce0: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
dcf0: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
dd00: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
dd10: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
dd20: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
dd30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
dd40: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
dd50: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
dd60: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
dd70: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
dd80: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
dd90: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
dda0: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
ddb0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
ddc0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
ddd0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
dde0: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
ddf0: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
de00: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
de10: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
de20: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
de30: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
de40: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
de50: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
de60: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
de70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
de80: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
de90: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
dea0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
deb0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
dec0: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
ded0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
dee0: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
def0: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
df00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
df10: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
df20: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
df30: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
df40: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
df50: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
df60: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
df70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
df80: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
df90: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
dfa0: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
dfb0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
dfc0: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
dfd0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
dfe0: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
dff0: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
e000: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
e010: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
e020: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
e030: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
e040: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
e050: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
e060: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
e070: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
e080: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
e090: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
e0a0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
e0b0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
e0c0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
e0d0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
e0e0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
e0f0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
e100: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
e110: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
e120: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
e130: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
e140: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
e150: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
e160: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
e170: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
e180: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
e190: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
e1a0: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
e1b0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
e1c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
e1d0: 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
e1e0: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
e1f0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
e200: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
e210: 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
e220: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
e230: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
e240: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
e250: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
e260: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
e270: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
e280: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
e290: 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
e2a0: 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
e2b0: 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
e2c0: 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
e2d0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
e2e0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
e2f0: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
e300: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
e310: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
e320: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
e330: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
e340: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
e350: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
e360: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
e370: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
e380: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
e390: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
e3a0: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
e3b0: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
e3c0: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
e3d0: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
e3e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e3f0: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
e400: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
e410: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
e420: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
e430: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
e440: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
e450: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
e460: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
e470: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
e480: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
e490: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
e4a0: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
e4b0: 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
e4c0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
e4d0: 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
e4e0: 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
e4f0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
e500: 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
e510: 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
e520: 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
e530: 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
e540: 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
e550: 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
e560: 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
e570: 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
e580: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
e590: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
e5a0: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
e5b0: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
e5c0: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
e5d0: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
e5e0: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
e5f0: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
e600: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
e610: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
e620: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
e630: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
e640: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
e650: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
e660: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
e670: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
e680: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
e690: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
e6a0: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
e6b0: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
e6c0: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
e6d0: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
e6e0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
e6f0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
e700: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
e710: 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
e720: 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
e730: 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
e740: 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
e750: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
e760: 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
e770: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
e780: 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
e790: 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
e7a0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
e7b0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
e7c0: 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
e7d0: 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
e7e0: 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
e7f0: 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
e800: 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
e810: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
e820: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
e830: 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
e840: 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
e850: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
e860: 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
e870: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
e880: 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
e890: 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
e8a0: 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
e8b0: 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
e8c0: 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
e8d0: 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
e8e0: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
e8f0: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
e900: 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
e910: 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
e920: 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
e930: 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
e940: 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
e950: 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
e960: 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
e970: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
e980: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
e990: 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
e9a0: 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
e9b0: 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
e9c0: 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
e9d0: 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
e9e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
e9f0: 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
ea00: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
ea10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
ea20: 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
ea30: 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
ea40: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
ea50: 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
ea60: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
ea70: 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
ea80: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
ea90: 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
eaa0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
eab0: 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
eac0: 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
ead0: 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
eae0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
eaf0: 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
eb00: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
eb10: 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
eb20: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
eb30: 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
eb40: 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
eb50: 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
eb60: 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
eb70: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
eb80: 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
eb90: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
eba0: 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
ebb0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
ebc0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
ebd0: 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
ebe0: 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
ebf0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
ec00: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
ec10: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
ec20: 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
ec30: 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
ec40: 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
ec50: 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
ec60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ec70: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
ec80: 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
ec90: 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
eca0: 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
ecb0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
ecc0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
ecd0: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
ece0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
ecf0: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
ed00: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
ed10: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
ed20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
ed30: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
ed40: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
ed50: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ed60: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
ed70: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
ed80: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
ed90: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
eda0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
edb0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
edc0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
edd0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
ede0: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
edf0: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
ee00: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
ee10: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
ee20: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
ee30: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
ee40: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
ee50: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
ee60: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
ee70: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
ee80: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
ee90: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
eea0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
eeb0: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
eec0: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
eed0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
eee0: 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
eef0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
ef00: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
ef10: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
ef20: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
ef30: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
ef40: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
ef50: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
ef60: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
ef70: 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
ef80: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
ef90: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
efa0: 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
efb0: 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
efc0: 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
efd0: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
efe0: 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
eff0: 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
f000: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
f010: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
f020: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
f030: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f040: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
f050: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
f060: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
f070: 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
f080: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
f090: 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
f0a0: 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
f0b0: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
f0c0: 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
f0d0: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
f0e0: 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
f0f0: 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
f100: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
f110: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
f120: 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
f130: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
f140: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
f150: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
f160: 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
f170: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
f180: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
f190: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
f1a0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
f1b0: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
f1c0: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
f1d0: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
f1e0: 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
f1f0: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
f200: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
f210: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
f220: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f230: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
f240: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
f250: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
f260: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
f270: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
f280: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
f290: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
f2a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
f2b0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
f2c0: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
f2d0: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
f2e0: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
f2f0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
f300: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
f310: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
f320: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
f330: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
f340: 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
f350: 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
f360: 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
f370: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
f380: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
f390: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
f3a0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
f3b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
f3c0: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
f3d0: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
f3e0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
f3f0: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
f400: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
f410: 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
f420: 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
f430: 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
f440: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
f450: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
f460: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
f470: 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
f480: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
f490: 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
f4a0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
f4b0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
f4c0: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
f4d0: 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
f4e0: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
f4f0: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
f500: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
f510: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
f520: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
f530: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
f540: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
f550: 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
f560: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
f570: 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
f580: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
f590: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
f5a0: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
f5b0: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
f5c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f5d0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
f5e0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
f5f0: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
f600: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
f610: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
f620: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f630: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
f640: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
f650: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
f660: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
f670: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
f680: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
f690: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
f6a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
f6b0: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
f6c0: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
f6d0: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
f6e0: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
f6f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
f700: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
f710: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
f720: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
f730: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
f740: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
f750: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
f760: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
f770: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
f780: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
f790: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
f7a0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
f7b0: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
f7c0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
f7d0: 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
f7e0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
f7f0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
f800: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
f810: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
f820: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
f830: 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
f840: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
f850: 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
f860: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
f870: 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
f880: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
f890: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f8a0: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
f8b0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
f8c0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
f8d0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
f8e0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
f8f0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
f900: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f910: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
f920: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
f930: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
f940: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
f950: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
f960: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
f970: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
f980: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
f990: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f9a0: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
f9b0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
f9c0: 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
f9d0: 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
f9e0: 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
f9f0: 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
fa00: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fa10: 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
fa20: 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
fa30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
fa40: 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
fa50: 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
fa60: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
fa70: 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
fa80: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
fa90: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
faa0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
fab0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
fac0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
fad0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
fae0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
faf0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
fb00: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
fb10: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
fb20: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
fb30: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
fb40: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
fb50: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
fb60: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
fb70: 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
fb80: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
fb90: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
fba0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
fbb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
fbc0: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
fbd0: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
fbe0: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
fbf0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
fc00: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
fc10: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
fc20: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
fc30: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
fc40: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
fc50: 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
fc60: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
fc70: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
fc80: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
fc90: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
fca0: 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
fcb0: 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
fcc0: 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
fcd0: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
fce0: 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
fcf0: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
fd00: 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
fd10: 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
fd20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fd30: 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
fd40: 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  e disabled, the 
fd50: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  .** following SQ
fd60: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
fd70: 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
fd80: 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
fd90: 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
fda0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
fdb0: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
fdc0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
fdd0: 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
fde0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
fdf0: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
fe00: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
fe10: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
fe20: 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
fe30: 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
fe40: 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
fe50: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
fe60: 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
fe70: 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
fe80: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
fe90: 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
fea0: 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
feb0: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
fec0: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
fed0: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
fee0: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
fef0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
ff00: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
ff10: 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
ff20: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
ff30: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
ff40: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
ff50: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
ff60: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
ff70: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
ff80: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
ff90: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
ffa0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
ffb0: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
ffc0: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
ffd0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
ffe0: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
fff0: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
10000 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
10010 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
10020 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
10030 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
10040 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
10050 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
10060 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
10070 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
10080 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
10090 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
100a0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
100b0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
100c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
100d0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
100e0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
100f0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
10100 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
10110 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
10120 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
10130 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
10140 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
10150 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
10160 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
10170 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
10180 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
10190 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
101a0 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
101b0 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
101c0 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
101d0 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
101e0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
101f0 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
10200 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
10210 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
10220 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
10230 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
10240 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
10250 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
10260 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
10270 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
10280 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
10290 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
102a0 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
102b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
102c0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
102d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
102e0 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
102f0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
10300 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
10310 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
10320 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
10330 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
10340 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
10350 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
10360 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
10370 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
10380 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
10390 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
103a0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
103b0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
103c0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
103d0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
103e0 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
103f0 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
10400 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
10410 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
10420 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
10430 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
10440 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
10450 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
10460 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
10470 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
10480 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
10490 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
104a0 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
104b0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
104c0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
104d0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
104e0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
104f0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
10500 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
10510 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
10520 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
10530 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
10540 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
10550 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
10560 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
10570 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
10580 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
10590 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
105a0 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
105b0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
105c0 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
105d0 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
105e0 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
105f0 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
10600 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
10610 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
10620 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
10630 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
10640 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
10650 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
10660 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
10670 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
10680 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
10690 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
106a0 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
106b0 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
106c0 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
106d0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
106e0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
106f0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
10700 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
10710 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
10720 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
10730 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
10740 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
10750 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
10760 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
10770 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
10780 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10790 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
107a0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
107b0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
107c0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
107d0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
107e0 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
107f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10800 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
10810 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10820 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
10830 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
10840 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
10850 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
10860 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
10870 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
10880 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
10890 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
108a0 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
108b0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
108c0 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
108d0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
108e0 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
108f0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
10900 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
10910 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
10920 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
10930 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
10940 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
10950 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
10960 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
10970 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
10980 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
10990 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
109a0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
109b0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
109c0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
109d0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
109e0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
109f0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
10a00 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
10a10 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
10a20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
10a30 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
10a40 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
10a50 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
10a60 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
10a70 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
10a80 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
10a90 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
10aa0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
10ab0 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
10ac0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
10ad0 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
10ae0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
10af0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
10b00 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
10b10 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
10b20 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
10b30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10b40 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
10b50 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
10b60 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
10b70 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
10b80 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
10b90 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
10ba0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
10bb0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
10bc0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
10bd0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
10be0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
10bf0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
10c00 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
10c10 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
10c20 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
10c30 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
10c40 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
10c50 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
10c60 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
10c70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10c80 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
10c90 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10ca0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10cb0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
10cc0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
10cd0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
10ce0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10cf0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
10d00 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
10d10 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
10d20 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
10d30 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
10d40 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
10d50 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
10d60 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
10d70 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
10d80 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
10d90 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
10da0 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
10db0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
10dc0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
10dd0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
10de0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
10df0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10e00 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
10e10 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10e20 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
10e30 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10e40 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
10e50 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
10e60 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
10e70 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
10e80 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
10e90 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
10ea0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
10eb0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
10ec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10ed0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
10ee0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
10ef0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
10f00 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
10f10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
10f20 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
10f30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10f40 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
10f50 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
10f60 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
10f70 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10f80 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10f90 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
10fa0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
10fb0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
10fc0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10fd0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
10fe0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
10ff0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
11000 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
11010 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
11020 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
11030 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
11040 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
11050 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
11060 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
11070 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
11080 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
11090 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
110a0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
110b0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
110c0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
110d0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
110e0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
110f0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
11100 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11110 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11120 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11130 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11140 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11150 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11160 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
11170 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
11180 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
11190 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
111a0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
111b0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
111c0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
111d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
111e0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
111f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
11200 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
11210 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
11220 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11230 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
11240 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
11250 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
11260 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11270 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11280 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
11290 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
112a0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
112b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
112c0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
112d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
112e0 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
112f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11300 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
11310 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
11320 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
11330 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
11340 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
11350 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
11360 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
11370 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
11380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11390 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
113a0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
113b0 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
113c0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
113d0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
113e0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
113f0 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
11400 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11410 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
11420 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
11430 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
11440 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
11450 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
11460 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
11470 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11480 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
11490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
114a0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
114b0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
114c0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
114d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
114e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
114f0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
11500 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
11510 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
11520 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
11530 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
11540 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
11550 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
11560 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
11570 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
11580 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
11590 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
115a0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
115b0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
115c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
115d0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
115e0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
115f0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
11600 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11610 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11620 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11630 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11640 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11650 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
11660 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
11670 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
11680 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
11690 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
116a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
116b0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
116c0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
116d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
116e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
116f0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
11700 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
11710 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
11720 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
11730 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
11740 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
11750 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
11760 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
11770 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
11780 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
11790 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
117a0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
117b0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
117c0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
117d0 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
117e0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
117f0 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
11800 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
11810 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
11820 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
11830 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
11840 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
11850 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
11860 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
11870 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
11880 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
11890 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
118a0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
118b0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
118c0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
118d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
118e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
118f0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
11900 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
11910 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
11920 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
11930 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
11940 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
11950 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
11960 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
11970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
11980 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
11990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
119a0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
119b0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
119c0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
119d0 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
119e0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
119f0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
11a00 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
11a10 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
11a20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
11a30 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
11a40 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
11a50 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
11a60 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
11a70 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
11a80 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
11a90 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
11aa0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
11ab0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
11ac0 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
11ad0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11ae0 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
11af0 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
11b00 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
11b10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
11b20 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
11b30 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
11b40 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
11b50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11b60 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _URI]] <dt>SQLIT
11b70 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
11b80 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e  <dd> This option
11b90 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
11ba0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
11bb0 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72   int. If non-zer
11bc0 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68  o, then.** URI h
11bd0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
11be0 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
11bf0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
11c00 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20   zero, then URI 
11c10 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67  handling.** is g
11c20 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
11c30 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e  . If URI handlin
11c40 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
11c50 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
11c60 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
11c70 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
11c80 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
11c90 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
11ca0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
11cb0 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
11cc0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
11cd0 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
11ce0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
11cf0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
11d00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
11d10 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
11d20 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
11d30 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
11d40 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
11d50 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49  ion is opened. I
11d60 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
11d70 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
11d80 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
11d90 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
11da0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
11db0 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
11dc0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
11dd0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
11de0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
11df0 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55  d. By default, U
11e00 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
11e10 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
11e20 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
11e30 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
11e40 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
11e50 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
11e60 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
11e70 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
11e80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11e90 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
11ea0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11eb0 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
11ec0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11ed0 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
11ee0 45 5f 43 4f 4e 46 4e 49 47 5f 47 45 54 50 43 41  E_CONFNIG_GETPCA
11ef0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
11f00 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
11f10 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
11f20 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
11f30 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
11f40 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
11f50 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
11f60 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
11f70 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
11f80 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
11f90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11fa0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
11fb0 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
11fc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11fd0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
11fe0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
11ff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12000 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
12010 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
12020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12030 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
12040 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
12050 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
12060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12070 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12080 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
12090 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
120a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
120b0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
120c0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
120d0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
120e0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
120f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
12100 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
12110 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
12120 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
12130 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
12140 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
12150 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
12160 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
12170 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12180 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
12190 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
121a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
121b0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
121c0 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
121d0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
121e0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
121f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12200 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
12210 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
12220 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
12230 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
12240 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
12250 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
12260 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
12270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12280 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
12290 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
122a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
122b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
122c0 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
122d0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
122e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
122f0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
12300 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
12310 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
12320 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
12330 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
12340 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12350 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
12360 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
12370 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12380 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12390 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
123a0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
123b0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
123c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
123d0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
123e0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
123f0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
12400 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12410 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
12420 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
12430 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
12440 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
12450 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
12460 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
12470 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
12480 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
12490 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
124a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
124b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
124c0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
124d0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
124e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
124f0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
12500 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
12510 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
12520 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
12530 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12540 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
12550 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
12560 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
12570 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
12580 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
12590 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
125a0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
125b0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
125c0 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
125d0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
125e0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
125f0 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
12600 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
12610 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
12620 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
12630 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
12640 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
12650 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
12660 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
12670 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12680 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
12690 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
126a0 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
126b0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
126c0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
126d0 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
126e0 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
126f0 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
12700 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
12710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12720 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
12730 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
12740 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
12750 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
12760 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
12770 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
12780 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
12790 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
127a0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
127b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
127c0 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
127d0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
127e0 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
127f0 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
12800 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
12810 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
12820 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
12830 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
12840 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12850 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
12860 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
12870 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
12880 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
12890 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
128a0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
128b0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
128c0 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
128d0 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
128e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
128f0 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
12900 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
12910 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
12920 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
12930 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
12940 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
12950 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
12960 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
12970 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
12980 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
12990 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
129a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
129b0 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
129c0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
129d0 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
129e0 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
129f0 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
12a00 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
12a10 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
12a20 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
12a30 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
12a40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
12a50 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
12a60 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
12a70 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
12a80 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
12a90 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
12aa0 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
12ab0 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
12ac0 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
12ad0 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
12ae0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
12af0 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
12b00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
12b10 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
12b20 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
12b30 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
12b40 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
12b50 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
12b60 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
12b70 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
12b80 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
12b90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
12ba0 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
12bb0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
12bc0 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
12bd0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
12be0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
12bf0 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
12c00 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
12c10 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
12c20 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
12c30 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
12c40 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
12c50 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
12c60 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
12c70 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
12c80 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
12c90 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
12ca0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
12cb0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
12cc0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
12cd0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
12ce0 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
12cf0 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
12d00 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
12d10 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
12d20 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
12d30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
12d40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
12d50 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
12d60 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
12d70 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
12d80 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
12d90 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
12da0 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
12db0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
12dc0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
12dd0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
12de0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
12df0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
12e00 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
12e10 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
12e20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
12e30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
12e40 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
12e50 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
12e60 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12e70 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
12e80 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
12e90 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
12ea0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
12eb0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
12ec0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
12ed0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
12ee0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
12ef0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
12f00 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
12f10 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
12f20 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
12f30 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
12f40 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
12f50 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
12f60 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
12f70 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
12f80 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
12f90 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
12fa0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
12fb0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
12fc0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
12fd0 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
12fe0 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
12ff0 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
13000 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
13010 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13020 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
13030 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
13040 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
13050 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
13060 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
13070 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
13080 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
13090 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
130a0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
130b0 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
130c0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
130d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
130e0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
130f0 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
13100 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
13110 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
13120 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
13130 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
13140 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
13150 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
13160 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
13170 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
13180 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
13190 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
131a0 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
131b0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
131c0 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
131d0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
131e0 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
131f0 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
13200 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
13210 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
13220 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
13230 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
13240 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
13250 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
13260 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
13270 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
13280 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
13290 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
132a0 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
132b0 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
132c0 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
132d0 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
132e0 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
132f0 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
13300 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
13310 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
13320 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
13330 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
13340 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
13350 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
13360 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
13370 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
13380 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
13390 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
133a0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
133b0 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
133c0 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
133d0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
133e0 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
133f0 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
13400 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
13410 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
13420 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
13430 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
13440 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
13450 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  id] of the most 
13460 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
13470 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
13480 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
13490 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
134a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
134b0 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
134c0 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66  rgument.  ^As of
134d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
134e0 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74  3.7.7, this rout
134f0 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20  ines.** records 
13500 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
13510 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72  rowid of both or
13520 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e  dinary tables an
13530 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  d [virtual table
13540 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75  s]..** ^If no su
13550 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
13560 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ]s.** have ever 
13570 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
13580 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13590 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
135a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  turned..**.** ^(
135b0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
135c0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
135d0 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
135e0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
135f0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
13600 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
13610 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
13620 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
13630 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
13640 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
13650 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
13660 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
13670 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
13680 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
13690 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
136a0 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
136b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
136c0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
136d0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
136e0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
136f0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
13700 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
13710 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
13720 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
13730 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
13740 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
13750 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
13760 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
13770 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
13780 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
13790 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
137a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
137b0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
137c0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
137d0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
137e0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
137f0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
13800 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
13810 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
13820 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
13830 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
13840 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
13850 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
13860 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
13870 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
13880 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
13890 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
138a0 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
138b0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
138c0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
138d0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
138e0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
138f0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
13900 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
13910 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
13920 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
13930 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
13940 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
13950 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
13960 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
13970 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
13980 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
13990 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
139a0 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
139b0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
139c0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
139d0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
139e0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
139f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
13a00 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
13a10 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
13a20 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
13a30 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
13a40 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
13a50 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
13a60 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
13a70 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
13a80 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
13a90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
13aa0 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
13ab0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
13ac0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
13ad0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
13ae0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
13af0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
13b00 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
13b10 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
13b20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
13b30 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
13b40 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
13b50 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
13b60 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
13b70 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
13b80 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
13b90 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
13ba0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
13bb0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
13bc0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
13bd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
13be0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
13bf0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
13c00 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
13c10 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
13c20 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
13c30 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
13c40 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
13c50 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
13c60 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
13c70 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
13c80 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
13c90 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
13ca0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
13cb0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
13cc0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
13cd0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
13ce0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
13cf0 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
13d00 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
13d10 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
13d20 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
13d30 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
13d40 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
13d50 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
13d60 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
13d70 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
13d80 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
13d90 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
13da0 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
13db0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
13dc0 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
13dd0 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
13de0 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
13df0 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
13e00 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
13e10 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
13e20 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
13e30 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
13e40 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
13e50 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
13e60 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
13e70 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
13e80 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
13e90 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
13ea0 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
13eb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
13ec0 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
13ed0 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
13ee0 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
13ef0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
13f00 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
13f10 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
13f20 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
13f30 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
13f40 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
13f50 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
13f60 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
13f70 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
13f80 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
13f90 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
13fa0 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
13fb0 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
13fc0 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
13fd0 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
13fe0 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
13ff0 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
14000 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
14010 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
14020 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
14030 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
14040 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
14050 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
14060 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
14070 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
14080 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
14090 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
140a0 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
140b0 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
140c0 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
140d0 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
140e0 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
140f0 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
14100 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
14110 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
14120 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
14130 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
14140 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
14150 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
14160 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
14170 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
14180 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
14190 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
141a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
141b0 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
141c0 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
141d0 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
141e0 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
141f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
14200 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
14210 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
14220 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
14230 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
14240 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
14250 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
14260 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
14270 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
14280 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
14290 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
142a0 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
142b0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
142c0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
142d0 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
142e0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
142f0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
14300 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
14310 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
14320 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
14330 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
14340 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
14350 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
14360 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
14370 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
14380 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
14390 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
143a0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
143b0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
143c0 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
143d0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
143e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
143f0 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
14400 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
14410 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
14420 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
14430 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
14440 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
14450 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
14460 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
14470 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
14480 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
14490 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
144a0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
144b0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
144c0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
144d0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
144e0 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
144f0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
14500 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
14510 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
14520 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
14530 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
14540 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
14550 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
14560 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
14570 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
14580 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
14590 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
145a0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
145b0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
145c0 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
145d0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
145e0 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
145f0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
14600 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
14610 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
14620 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
14630 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
14640 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c  sed by [INSERT],
14650 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  .** [UPDATE] or 
14660 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
14670 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
14680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14690 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
146a0 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72  ** ^(The count r
146b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
146c0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
146d0 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
146e0 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20  changes.** from 
146f0 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47  all [CREATE TRIG
14700 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63  GER | trigger] c
14710 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e  ontexts and chan
14720 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b  ges made by.** [
14730 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
14740 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a  ons]. However,.*
14750 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
14760 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
14770 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
14780 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d  lement [REPLACE]
14790 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
147a0 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
147b0 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
147c0 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c  g, or [DROP TABL
147d0 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20  E] processing.  
147e0 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65  The.** count doe
147f0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f  s not include ro
14800 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74  ws of views that
14810 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41   fire an [INSTEA
14820 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a  D OF trigger],.*
14830 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20  * though if the 
14840 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
14850 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  er makes changes
14860 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f   of its own, tho
14870 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61  se changes .** a
14880 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a  re counted.)^.**
14890 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f   ^The sqlite3_to
148a0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75  tal_changes() fu
148b0 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68  nction counts th
148c0 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f  e changes as soo
148d0 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74  n as.** the stat
148e0 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
148f0 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74   them is complet
14900 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
14910 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a  tement handle.**
14920 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
14930 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
14940 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
14950 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
14960 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
14970 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
14980 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
14990 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
149a0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
149b0 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
149c0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
149d0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
149e0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
149f0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
14a00 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
14a10 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
14a20 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
14a30 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
14a40 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
14a50 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
14a60 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
14a70 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
14a80 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
14a90 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
14aa0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
14ab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14ac0 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
14ad0 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
14ae0 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
14af0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
14b00 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
14b10 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
14b20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
14b30 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
14b40 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
14b50 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
14b60 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
14b70 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
14b80 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
14b90 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
14ba0 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
14bb0 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
14bc0 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
14bd0 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
14be0 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
14bf0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
14c00 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
14c10 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
14c20 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
14c30 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
14c40 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
14c50 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
14c60 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
14c70 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
14c80 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
14c90 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
14ca0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
14cb0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
14cc0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
14cd0 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
14ce0 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
14cf0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
14d00 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
14d10 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
14d20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
14d30 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
14d40 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
14d50 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
14d60 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
14d70 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
14d80 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
14d90 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
14da0 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
14db0 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
14dc0 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
14dd0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
14de0 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
14df0 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
14e00 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
14e10 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
14e20 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
14e30 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
14e40 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
14e50 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
14e60 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
14e70 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
14e80 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
14e90 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
14ea0 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
14eb0 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
14ec0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
14ed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
14ee0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
14ef0 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
14f00 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
14f10 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
14f20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
14f30 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
14f40 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
14f50 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
14f60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
14f70 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
14f80 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
14f90 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
14fa0 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
14fb0 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
14fc0 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
14fd0 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
14fe0 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
14ff0 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
15000 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
15010 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
15020 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
15030 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
15040 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
15050 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
15060 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
15070 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
15080 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
15090 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
150a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
150b0 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
150c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
150d0 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
150e0 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
150f0 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
15100 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
15110 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
15120 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
15130 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
15140 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
15150 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
15160 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15170 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
15180 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
15190 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
151a0 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
151b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
151c0 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
151d0 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
151e0 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
151f0 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ppen..*/.void sq
15200 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15210 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
15220 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
15230 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
15240 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
15250 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
15260 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
15270 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
15280 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
15290 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
152a0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
152b0 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
152c0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
152d0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
152e0 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
152f0 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
15300 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
15310 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
15320 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
15330 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
15340 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
15350 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
15360 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
15370 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
15380 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
15390 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
153a0 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
153b0 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
153c0 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
153d0 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
153e0 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
153f0 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
15400 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
15410 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
15420 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
15430 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
15440 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
15450 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
15460 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
15470 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
15480 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
15490 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
154a0 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
154b0 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
154c0 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
154d0 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
154e0 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
154f0 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
15500 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
15510 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
15520 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
15530 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
15540 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
15550 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
15560 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
15570 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
15580 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
15590 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
155a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
155b0 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
155c0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
155d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
155e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
155f0 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
15600 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
15610 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
15620 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
15630 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
15640 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
15650 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
15660 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
15670 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
15680 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
15690 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
156a0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
156b0 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
156c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
156d0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
156e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
156f0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
15700 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
15710 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
15720 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
15730 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
15740 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
15750 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
15760 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
15770 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
15780 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
15790 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
157a0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
157b0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
157c0 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
157d0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
157e0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
157f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
15800 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
15810 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
15820 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
15830 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
15840 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
15850 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
15860 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
15870 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
15880 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
15890 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
158a0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
158b0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
158c0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
158d0 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
158e0 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
158f0 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
15900 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
15910 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
15920 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
15930 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
15940 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
15950 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
15960 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
15970 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
15980 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
15990 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
159a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
159b0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
159c0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
159d0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
159e0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
159f0 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
15a00 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
15a10 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
15a20 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
15a30 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
15a40 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
15a50 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
15a60 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
15a70 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
15a80 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
15a90 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15aa0 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
15ab0 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
15ac0 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
15ad0 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
15ae0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
15af0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
15b00 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
15b10 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
15b20 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
15b30 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
15b40 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
15b50 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
15b60 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
15b70 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
15b80 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
15b90 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
15ba0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
15bb0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
15bc0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
15bd0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
15be0 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
15bf0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
15c00 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
15c10 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
15c20 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
15c30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
15c40 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
15c50 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
15c60 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
15c70 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
15c80 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
15c90 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
15ca0 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
15cb0 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
15cc0 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
15cd0 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
15ce0 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
15cf0 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
15d00 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
15d10 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
15d20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
15d30 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
15d40 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
15d50 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
15d60 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
15d70 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
15d80 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
15d90 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
15da0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
15db0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
15dc0 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
15dd0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
15de0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
15df0 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
15e00 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
15e10 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
15e20 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
15e30 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
15e40 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
15e50 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
15e60 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
15e70 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
15e80 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
15e90 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
15ea0 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
15eb0 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
15ec0 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
15ed0 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
15ee0 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
15ef0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
15f00 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
15f10 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
15f20 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
15f30 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
15f40 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
15f50 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
15f60 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
15f70 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
15f80 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
15f90 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
15fa0 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
15fb0 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
15fc0 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
15fd0 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
15fe0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
15ff0 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
16000 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
16010 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
16020 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
16030 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
16040 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
16050 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
16060 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
16070 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
16080 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
16090 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
160a0 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
160b0 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
160c0 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
160d0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
160e0 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
160f0 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
16100 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
16110 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
16120 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
16130 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
16140 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
16150 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
16160 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
16170 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
16180 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
16190 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
161a0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
161b0 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
161c0 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
161d0 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
161e0 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
161f0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
16200 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
16210 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
16220 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
16230 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
16240 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
16250 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
16260 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
16270 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
16280 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
16290 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
162a0 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
162b0 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
162c0 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
162d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
162e0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
162f0 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
16300 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
16310 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
16320 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
16330 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
16340 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
16350 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
16360 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
16370 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
16380 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
16390 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
163a0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
163b0 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
163c0 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
163d0 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
163e0 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
163f0 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
16400 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
16410 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
16420 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
16430 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
16440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16450 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
16460 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
16470 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
16480 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
16490 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
164a0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
164b0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
164c0 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
164d0 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
164e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
164f0 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
16500 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
16510 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
16520 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
16530 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
16540 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
16550 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
16560 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
16570 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
16580 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
16590 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
165a0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
165b0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
165c0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
165d0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
165e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
165f0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
16600 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
16610 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
16620 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
16630 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
16640 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
16650 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
16660 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
16670 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20  y Timeout.**.** 
16680 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
16690 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
166a0 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
166b0 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
166c0 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
166d0 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
166e0 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
166f0 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
16700 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
16710 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
16720 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
16730 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
16740 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
16750 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
16760 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
16770 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
16780 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
16790 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
167a0 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
167b0 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
167c0 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
167d0 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
167e0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
167f0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
16800 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
16810 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
16820 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
16830 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
16840 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
16850 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
16860 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
16870 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
16880 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
16890 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
168a0 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
168b0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
168c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
168d0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
168e0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
168f0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
16900 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
16910 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
16920 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
16930 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
16940 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
16950 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
16960 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
16970 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  d.)^.*/.int sqli
16980 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
16990 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
169a0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
169b0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
169c0 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
169d0 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
169e0 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
169f0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
16a00 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
16a10 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
16a20 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
16a30 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
16a40 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
16a50 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
16a60 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
16a70 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
16a80 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
16a90 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
16aa0 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
16ab0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
16ac0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
16ad0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
16ae0 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
16af0 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
16b00 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
16b10 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
16b20 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
16b30 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
16b40 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
16b50 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
16b60 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
16b70 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
16b80 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
16b90 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
16ba0 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
16bb0 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
16bc0 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
16bd0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
16be0 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
16bf0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
16c00 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
16c10 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
16c20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
16c30 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
16c40 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
16c50 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
16c60 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
16c70 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
16c80 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
16c90 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
16ca0 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
16cb0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
16cc0 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
16cd0 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
16ce0 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
16cf0 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
16d00 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
16d10 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
16d20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
16d30 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
16d40 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
16d50 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
16d60 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
16d70 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
16d80 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
16d90 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
16da0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
16db0 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
16dc0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
16dd0 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
16de0 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
16df0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
16e00 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
16e10 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
16e20 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
16e30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
16e40 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
16e50 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
16e60 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
16e70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
16e80 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
16e90 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
16ea0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
16eb0 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
16ec0 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
16ed0 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
16ee0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
16ef0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
16f00 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
16f10 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
16f20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
16f30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
16f40 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
16f50 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
16f60 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
16f70 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
16f80 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
16f90 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
16fa0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
16fb0 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
16fc0 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
16fd0 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
16fe0 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
16ff0 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
17000 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
17010 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
17020 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
17030 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
17040 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
17050 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
17060 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
17070 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
17080 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
17090 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
170a0 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
170b0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
170c0 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
170d0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
170e0 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
170f0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
17100 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
17110 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
17120 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
17130 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
17140 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
17150 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
17160 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
17170 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
17180 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
17190 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
171a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
171b0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
171c0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
171d0 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
171e0 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
171f0 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
17200 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
17210 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
17220 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
17230 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
17240 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
17250 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
17260 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
17270 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
17280 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
17290 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
172a0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
172b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
172c0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
172d0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
172e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
172f0 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
17300 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
17310 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
17320 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
17330 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
17340 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
17350 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
17360 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
17370 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
17380 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
17390 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
173a0 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
173b0 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
173c0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
173d0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
173e0 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
173f0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
17400 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
17410 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
17420 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
17430 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
17440 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
17450 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
17460 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
17470 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
17480 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
17490 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
174a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
174b0 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
174c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
174d0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
174e0 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
174f0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
17500 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
17510 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
17520 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
17530 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
17540 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
17550 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
17560 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
17570 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
17580 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
17590 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
175a0 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
175b0 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
175c0 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
175d0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
175e0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
175f0 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
17600 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
17610 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
17620 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
17630 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
17640 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
17650 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
17660 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
17670 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
17680 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
17690 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
176a0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
176b0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
176c0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
176d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
176e0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
176f0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
17700 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
17710 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
17720 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
17730 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
17740 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
17750 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
17760 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
17770 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
17780 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
17790 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
177a0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
177b0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
177c0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
177d0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
177e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
177f0 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
17800 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
17810 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
17820 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
17830 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
17840 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
17850 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
17860 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
17870 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
17880 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
17890 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
178a0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
178b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
178c0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
178d0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
178e0 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
178f0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
17900 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
17910 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
17920 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
17930 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
17940 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
17950 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
17960 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
17970 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
17980 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
17990 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
179a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
179b0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
179c0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
179d0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
179e0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
179f0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
17a00 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
17a10 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
17a20 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
17a30 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
17a40 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17a50 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
17a60 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
17a70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
17a80 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
17a90 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
17aa0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
17ab0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
17ac0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
17ad0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
17ae0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
17af0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
17b00 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
17b10 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
17b20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
17b30 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
17b40 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
17b50 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
17b60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
17b70 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
17b80 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
17b90 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
17ba0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
17bb0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
17bc0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
17bd0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
17be0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
17bf0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
17c00 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
17c10 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
17c20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
17c30 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
17c40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
17c50 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
17c60 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
17c70 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
17c80 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
17c90 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
17ca0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
17cb0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
17cc0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
17cd0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
17ce0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
17cf0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
17d00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
17d10 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
17d20 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
17d30 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
17d40 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
17d50 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
17d60 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
17d70 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
17d80 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
17d90 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
17da0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
17db0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
17dc0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
17dd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
17de0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
17df0 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
17e00 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
17e10 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
17e20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
17e30 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
17e40 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
17e50 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
17e60 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
17e70 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
17e80 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
17e90 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
17ea0 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
17eb0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
17ec0 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
17ed0 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
17ee0 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
17ef0 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
17f00 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
17f10 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
17f20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
17f30 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
17f40 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d  utes a null-term
17f50 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
17f60 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
17f70 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
17f80 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
17f90 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
17fa0 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
17fb0 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
17fc0 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
17fd0 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
17fe0 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
17ff0 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
18000 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
18010 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
18020 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
18030 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
18040 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
18050 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
18060 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
18070 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
18080 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
18090 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
180a0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
180b0 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
180c0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
180d0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
180e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
180f0 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
18100 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
18110 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
18120 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
18130 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
18140 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
18150 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
18160 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
18170 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
18180 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
18190 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
181a0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
181b0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
181c0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
181d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
181e0 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
181f0 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
18200 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
18210 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
18220 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
18230 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
18240 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
18250 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
18260 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
18270 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
18280 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
18290 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
182a0 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
182b0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
182c0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
182d0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
182e0 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
182f0 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
18300 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
18310 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
18320 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
18330 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
18340 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
18350 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
18360 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
18370 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
18380 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
18390 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
183a0 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
183b0 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
183c0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
183d0 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
183e0 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
183f0 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
18400 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
18410 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
18420 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
18430 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
18440 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
18450 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
18460 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
18470 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
18480 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
18490 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
184a0 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
184b0 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
184c0 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
184d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
184e0 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
184f0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
18500 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
18510 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
18520 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
18530 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
18540 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
18550 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
18560 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
18570 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
18580 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
18590 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
185a0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
185b0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
185c0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
185d0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
185e0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
185f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
18600 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
18610 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
18620 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
18630 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
18640 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
18650 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
18660 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
18670 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
18680 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
18690 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
186a0 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
186b0 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
186c0 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
186d0 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
186e0 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
186f0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
18700 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
18710 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
18720 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
18730 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
18740 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
18750 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
18760 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
18770 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
18780 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
18790 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
187a0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
187b0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
187c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
187d0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
187e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
187f0 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
18800 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
18810 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
18820 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
18830 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
18840 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
18850 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
18860 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
18870 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
18880 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
18890 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
188a0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
188b0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
188c0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
188d0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
188e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
188f0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
18900 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
18910 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
18920 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
18930 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
18940 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
18950 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
18960 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
18970 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
18980 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
18990 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
189a0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
189b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
189c0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
189d0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
189e0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
189f0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
18a00 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
18a10 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
18a20 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
18a30 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
18a40 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
18a50 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
18a60 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
18a70 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
18a80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
18a90 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
18aa0 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
18ab0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
18ac0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
18ad0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
18ae0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
18af0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
18b00 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
18b10 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
18b20 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
18b30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
18b40 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
18b50 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
18b60 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
18b70 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
18b80 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
18b90 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
18ba0 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
18bb0 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
18bc0 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
18bd0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
18be0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
18bf0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
18c00 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
18c10 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
18c20 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
18c30 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
18c40 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
18c50 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
18c60 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
18c70 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
18c80 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
18c90 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
18ca0 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
18cb0 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
18cc0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
18cd0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
18ce0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
18cf0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
18d00 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
18d10 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
18d20 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
18d30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
18d40 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
18d50 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
18d60 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
18d70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
18d80 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
18d90 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
18da0 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
18db0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
18dc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
18dd0 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
18de0 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
18df0 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
18e00 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
18e10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
18e20 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
18e30 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
18e40 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
18e50 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
18e60 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
18e70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
18e80 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
18e90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18ea0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
18eb0 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
18ec0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18ed0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
18ee0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
18ef0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
18f00 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
18f10 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
18f20 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
18f30 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
18f40 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
18f50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18f60 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
18f70 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
18f80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
18f90 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
18fa0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
18fb0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
18fc0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
18fd0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
18fe0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
18ff0 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
19000 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
19010 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
19020 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
19030 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
19040 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
19050 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
19060 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
19070 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
19080 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
19090 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
190a0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
190b0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
190c0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
190d0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
190e0 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
190f0 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
19100 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
19110 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
19120 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
19130 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
19140 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
19150 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19160 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
19170 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
19180 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
19190 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a  ndary, or to a.*
191a0 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72  * 4 byte boundar
191b0 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  y if the [SQLITE
191c0 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f  _4_BYTE_ALIGNED_
191d0 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d  MALLOC] compile-
191e0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  time.** option i
191f0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  s used..**.** In
19200 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
19210 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
19220 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
19230 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
19240 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
19250 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
19260 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
19270 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
19280 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
19290 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
192a0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
192b0 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
192c0 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
192d0 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
192e0 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
192f0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
19300 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
19310 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   The Windows OS 
19320 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
19330 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
19340 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
19350 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
19360 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
19370 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
19380 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
19390 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
193a0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
193b0 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
193c0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
193d0 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
193e0 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
193f0 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
19400 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
19410 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
19420 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
19430 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
19440 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
19450 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
19460 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
19470 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
19480 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
19490 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
194a0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
194b0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
194c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
194d0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
194e0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
194f0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
19500 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
19510 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
19520 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
19530 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
19540 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
19550 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
19560 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
19570 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
19580 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
19590 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
195a0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
195b0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
195c0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
195d0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
195e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
195f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
19600 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
19610 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
19620 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
19630 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
19640 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
19650 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
19660 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19670 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
19680 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
19690 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
196a0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
196b0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
196c0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
196d0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
196e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
196f0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
19700 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
19710 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
19720 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
19730 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
19740 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
19750 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
19760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
19770 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
19780 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
19790 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
197a0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
197b0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
197c0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
197d0 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
197e0 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
197f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
19800 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
19810 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
19820 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
19830 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
19840 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
19850 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
19860 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
19870 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
19880 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
19890 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
198a0 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
198b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
198c0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
198d0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
198e0 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
198f0 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
19900 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
19910 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19920 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
19930 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
19940 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
19950 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
19960 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
19970 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
19980 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
19990 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
199a0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
199b0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
199c0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
199d0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
199e0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
199f0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
19a00 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
19a10 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
19a20 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
19a30 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
19a40 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
19a50 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
19a60 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
19a70 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
19a80 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
19a90 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
19aa0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
19ab0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
19ac0 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
19ad0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
19ae0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
19af0 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
19b00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19b10 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
19b20 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a  umber Generator.
19b30 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
19b40 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
19b50 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
19b60 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
19b70 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
19b80 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
19b90 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57  dom [ROWID | ROW
19ba0 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74  IDs] when insert
19bb0 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
19bc0 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
19bd0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
19be0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
19bf0 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20  ssible [ROWID]. 
19c00 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
19c10 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
19c20 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
19c30 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
19c40 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
19c50 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
19c60 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
19c70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
19c80 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
19c90 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
19ca0 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  poses..**.** ^A 
19cb0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
19cc0 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
19cd0 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
19ce0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
19cf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
19d00 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74  t time this rout
19d10 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  ine is invoked (
19d20 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c  either internall
19d30 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61  y or by.** the a
19d40 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20  pplication) the 
19d50 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75  PRNG is seeded u
19d60 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
19d70 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
19d80 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
19d90 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
19da0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
19db0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
19dc0 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ^On all subseque
19dd0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
19de0 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
19df0 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
19e00 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
19e10 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
19e20 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
19e30 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
19e40 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
19e50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
19e60 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
19e70 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
19e80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19e90 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
19ea0 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
19eb0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
19ec0 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
19ed0 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
19ee0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
19ef0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
19f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19f10 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
19f20 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
19f30 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
19f40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19f50 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
19f60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
19f70 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
19f80 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
19f90 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
19fa0 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
19fb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19fc0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
19fd0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
19fe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19ff0 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
1a000 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
1a010 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
1a020 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
1a030 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
1a040 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
1a050 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
1a060 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
1a070 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1a080 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
1a090 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
1a0a0 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
1a0b0 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
1a0c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
1a0d0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
1a0e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
1a0f0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
1a100 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1a110 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
1a120 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
1a130 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
1a140 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1a150 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
1a160 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
1a170 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
1a180 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
1a190 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
1a1a0 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
1a1b0 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
1a1c0 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
1a1d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1a1e0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
1a1f0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1a200 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
1a210 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
1a220 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
1a230 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
1a240 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1a250 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1a260 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1a270 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
1a280 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1a290 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1a2a0 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
1a2b0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1a2c0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
1a2d0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
1a2e0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
1a2f0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
1a300 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
1a310 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1a320 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
1a330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1a340 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1a350 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1a360 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
1a370 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
1a380 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1a390 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
1a3a0 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
1a3b0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
1a3c0 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
1a3d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1a3e0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1a3f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
1a400 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
1a410 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1a420 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1a430 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
1a440 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
1a450 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
1a460 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1a470 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1a480 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
1a490 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
1a4a0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
1a4b0 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
1a4c0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1a4d0 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
1a4e0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
1a4f0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
1a500 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1a510 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a520 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
1a530 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
1a540 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
1a550 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
1a560 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
1a570 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
1a580 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1a590 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
1a5a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1a5b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
1a5c0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
1a5d0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1a5e0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
1a5f0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
1a600 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
1a610 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
1a620 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
1a630 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1a640 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
1a650 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
1a660 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
1a670 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
1a680 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
1a690 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
1a6a0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
1a6b0 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
1a6c0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
1a6d0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
1a6e0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
1a6f0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1a700 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
1a710 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
1a720 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1a730 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1a740 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
1a750 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
1a760 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
1a770 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
1a780 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
1a790 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
1a7a0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
1a7b0 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
1a7c0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
1a7d0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
1a7e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1a7f0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
1a800 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
1a810 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
1a820 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
1a830 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
1a840 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
1a850 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
1a860 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
1a870 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
1a880 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
1a890 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
1a8a0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
1a8b0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
1a8c0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
1a8d0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
1a8e0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
1a8f0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
1a900 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
1a910 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
1a920 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
1a930 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
1a940 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
1a950 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1a960 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
1a970 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
1a980 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
1a990 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
1a9a0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
1a9b0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
1a9c0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
1a9d0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
1a9e0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
1a9f0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
1aa00 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1aa10 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
1aa20 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
1aa30 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
1aa40 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
1aa50 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
1aa60 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1aa70 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
1aa80 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
1aa90 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
1aaa0 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
1aab0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
1aac0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
1aad0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1aae0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
1aaf0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
1ab00 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
1ab10 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1ab20 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
1ab30 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
1ab40 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
1ab50 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
1ab60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
1ab70 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
1ab80 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1ab90 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
1aba0 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
1abb0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
1abc0 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
1abd0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
1abe0 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
1abf0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
1ac00 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
1ac10 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
1ac20 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
1ac30 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
1ac40 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
1ac50 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1ac60 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1ac70 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1ac80 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1ac90 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1aca0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1acb0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
1acc0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1acd0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1ace0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1acf0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1ad00 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1ad10 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1ad20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ad30 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1ad40 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1ad50 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1ad60 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
1ad70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ad80 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
1ad90 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
1ada0 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
1adb0 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
1adc0 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
1add0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1ade0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
1adf0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
1ae00 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
1ae10 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
1ae20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
1ae30 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
1ae40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1ae50 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
1ae60 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
1ae70 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1ae80 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
1ae90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1aea0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1aeb0 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
1aec0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1aed0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1aee0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
1aef0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
1af00 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
1af10 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
1af20 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
1af30 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
1af40 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
1af50 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
1af60 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
1af70 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
1af80 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
1af90 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
1afa0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
1afb0 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
1afc0 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
1afd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1afe0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
1aff0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
1b000 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1b010 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1b020 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1b030 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
1b040 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
1b050 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b060 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
1b070 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
1b080 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1b090 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1b0a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1b0b0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1b0c0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1b0d0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1b0e0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1b0f0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1b100 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1b110 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1b120 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1b130 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1b140 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1b150 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1b160 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1b170 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1b180 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
1b190 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1b1a0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
1b1b0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
1b1c0 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
1b1d0 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
1b1e0 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d  K | return code]
1b1f0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  .** from the [sq
1b200 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
1b210 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
1b220 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
1b230 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
1b240 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
1b250 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
1b260 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
1b270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
1b280 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
1b290 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
1b2a0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
1b2b0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
1b2c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1b2d0 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
1b2e0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1b2f0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1b300 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
1b310 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
1b320 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1b330 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
1b340 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
1b350 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
1b360 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
1b370 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
1b380 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
1b390 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1b3a0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
1b3b0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1b3c0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
1b3d0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
1b3e0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
1b3f0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
1b400 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
1b410 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1b420 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
1b430 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
1b440 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
1b450 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
1b460 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
1b470 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
1b480 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
1b490 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
1b4a0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
1b4b0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
1b4c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1b4d0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
1b4e0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
1b4f0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
1b500 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
1b510 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1b520 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1b530 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
1b540 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
1b550 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b560 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
1b570 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1b580 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
1b590 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
1b5a0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
1b5b0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
1b5c0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1b5d0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
1b5e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1b5f0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
1b600 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
1b610 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1b620 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
1b630 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
1b640 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
1b650 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
1b660 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
1b670 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
1b680 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
1b690 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b6a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b6b0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
1b6c0 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
1b6d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b6e0 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
1b6f0 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
1b700 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1b710 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b720 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b730 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
1b740 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
1b750 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1b760 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b780 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
1b790 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
1b7a0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1b7b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b7c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1b7d0 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
1b7e0 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
1b7f0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1b800 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1b820 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
1b830 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
1b840 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1b850 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1b860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1b870 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
1b880 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
1b890 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1b8a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b8b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1b8c0 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
1b8d0 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
1b8e0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1b8f0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1b900 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b910 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
1b920 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
1b930 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1b940 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b950 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
1b960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b970 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1b980 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1b990 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b9a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
1b9b0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
1b9c0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1b9d0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1b9e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b9f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
1ba00 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
1ba10 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1ba20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ba30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ba40 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1ba50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
1ba60 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1ba70 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ba80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ba90 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1baa0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
1bab0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1bac0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1bad0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bae0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1baf0 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
1bb00 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1bb10 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1bb20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1bb30 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
1bb40 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
1bb50 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1bb60 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1bb70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1bb80 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
1bb90 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
1bba0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1bbb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1bbc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1bbd0 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
1bbe0 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
1bbf0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1bc00 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1bc10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bc20 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
1bc30 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
1bc40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1bc50 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1bc60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bc70 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
1bc80 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
1bc90 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
1bca0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
1bcb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1bcc0 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
1bcd0 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
1bce0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1bcf0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1bd00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
1bd10 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
1bd20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
1bd30 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
1bd40 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1bd50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
1bd60 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
1bd70 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
1bd80 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
1bd90 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1bda0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
1bdb0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1bdc0 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
1bdd0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1bde0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1bdf0 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
1be00 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1be10 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
1be20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1be30 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1be40 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
1be50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1be60 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
1be70 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
1be80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1be90 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
1bea0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
1beb0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1bec0 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
1bed0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1bee0 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
1bef0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
1bf00 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1bf10 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1bf20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1bf30 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
1bf40 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
1bf50 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1bf60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1bf70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1bf80 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
1bf90 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
1bfa0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1bfb0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1bfc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bfd0 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
1bfe0 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
1bff0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1c000 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1c010 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c020 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
1c030 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
1c040 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c050 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
1c060 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c070 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
1c080 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
1c090 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1c0a0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
1c0b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c0c0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
1c0d0 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
1c0e0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
1c0f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c100 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
1c110 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
1c120 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1c130 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
1c140 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c150 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
1c160 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
1c170 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
1c180 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
1c190 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
1c1a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
1c1b0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1c1c0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1c1d0 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
1c1e0 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
1c1f0 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
1c200 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1c210 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
1c220 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
1c230 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
1c240 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
1c250 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1c260 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
1c270 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
1c280 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1c290 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
1c2a0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
1c2b0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
1c2c0 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
1c2d0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1c2e0 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
1c2f0 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
1c300 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
1c310 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
1c320 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
1c330 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
1c340 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
1c350 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
1c360 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
1c370 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  igger.)^.**.** ^
1c380 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1c390 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1c3a0 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
1c3b0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
1c3c0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
1c3d0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
1c3e0 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
1c3f0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
1c400 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
1c410 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
1c420 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
1c430 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
1c440 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
1c450 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
1c460 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
1c470 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
1c480 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
1c490 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
1c4a0 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
1c4b0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
1c4c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
1c4d0 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
1c4e0 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
1c4f0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
1c500 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
1c510 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
1c520 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
1c530 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
1c540 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1c550 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
1c560 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
1c570 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
1c580 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
1c590 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
1c5a0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
1c5b0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
1c5c0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
1c5d0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
1c5e0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
1c5f0 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
1c600 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
1c610 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1c620 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
1c630 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
1c640 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1c650 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
1c660 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
1c670 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
1c680 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
1c690 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
1c6a0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1c6b0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
1c6c0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
1c6d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
1c6e0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
1c6f0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1c700 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
1c710 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
1c720 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
1c730 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
1c740 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
1c750 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
1c760 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1c770 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1c780 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
1c790 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
1c7a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
1c7b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
1c7c0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
1c7d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c7e0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
1c7f0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
1c800 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1c810 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
1c820 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
1c830 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
1c840 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
1c850 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
1c860 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
1c870 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1c880 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
1c890 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
1c8a0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
1c8b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  the number of .*
1c8c0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
1c8d0 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
1c8e0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
1c8f0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
1c900 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
1c910 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
1c920 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e  lback X..**.** ^
1c930 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
1c940 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
1c950 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
1c960 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
1c970 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c980 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
1c990 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
1c9a0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
1c9b0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
1c9c0 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
1c9d0 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
1c9e0 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
1c9f0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
1ca00 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1ca10 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
1ca20 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
1ca30 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
1ca40 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
1ca50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
1ca60 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
1ca70 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1ca80 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
1ca90 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
1caa0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
1cab0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
1cac0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
1cad0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
1cae0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
1caf0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
1cb00 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
1cb10 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
1cb20 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1cb30 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1cb40 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1cb50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1cb60 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1cb70 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1cb80 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
1cb90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cba0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1cbb0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1cbc0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1cbd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1cbe0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1cbf0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1cc00 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1cc10 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
1cc20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1cc30 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1cc40 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
1cc50 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
1cc60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cc70 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
1cc80 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
1cc90 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
1cca0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
1ccb0 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1ccc0 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
1ccd0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
1cce0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
1ccf0 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
1cd00 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
1cd10 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
1cd20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1cd30 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1cd40 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
1cd50 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1cd60 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
1cd70 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
1cd80 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
1cd90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cda0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
1cdb0 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
1cdc0 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
1cdd0 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
1cde0 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
1cdf0 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
1ce00 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
1ce10 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1ce20 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
1ce30 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
1ce40 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
1ce50 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
1ce60 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
1ce70 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
1ce80 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
1ce90 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
1cea0 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
1ceb0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
1cec0 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
1ced0 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
1cee0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
1cef0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
1cf00 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
1cf10 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1cf20 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
1cf30 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1cf40 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
1cf50 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
1cf60 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
1cf70 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
1cf80 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
1cf90 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
1cfa0 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
1cfb0 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
1cfc0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
1cfd0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
1cfe0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
1cff0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
1d000 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
1d010 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
1d020 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33  -8 if.** sqlite3
1d030 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1d040 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1d050 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
1d060 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1d070 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
1d080 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1d090 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ) is used..**.**
1d0a0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
1d0b0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
1d0c0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
1d0d0 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
1d0e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1d0f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1d100 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1d110 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
1d120 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
1d130 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
1d140 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
1d150 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
1d160 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
1d170 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
1d180 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
1d190 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
1d1a0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
1d1b0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
1d1c0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
1d1d0 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
1d1e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
1d1f0 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
1d200 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
1d210 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
1d220 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
1d230 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
1d240 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
1d250 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
1d260 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
1d270 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
1d280 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
1d290 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1d2a0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
1d2b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1d2c0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
1d2d0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1d2e0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
1d2f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1d300 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
1d310 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
1d320 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
1d330 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1d340 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
1d350 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1d360 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1d370 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
1d380 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
1d390 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1d3a0 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
1d3b0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1d3c0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
1d3d0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1d3e0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1d3f0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1d400 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1d410 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1d420 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1d430 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
1d440 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
1d450 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
1d460 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
1d470 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1d480 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
1d490 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
1d4a0 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
1d4b0 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
1d4c0 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
1d4d0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1d4e0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1d4f0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1d500 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
1d510 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
1d520 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1d530 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1d540 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
1d550 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
1d560 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
1d570 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
1d580 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
1d590 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
1d5a0 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
1d5b0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1d5c0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1d5d0 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
1d5e0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
1d5f0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
1d600 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1d610 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
1d620 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
1d630 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
1d640 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
1d650 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1d660 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
1d670 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1d680 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
1d690 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
1d6a0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1d6b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1d6c0 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
1d6d0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
1d6e0 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
1d6f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d700 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
1d710 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
1d720 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
1d730 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
1d740 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
1d750 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
1d760 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
1d770 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1d780 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
1d790 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1d7a0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
1d7b0 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
1d7c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d7d0 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
1d7e0 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
1d7f0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
1d800 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
1d810 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
1d820 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
1d830 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
1d840 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1d850 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
1d860 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1d870 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1d880 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1d890 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
1d8a0 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
1d8b0 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
1d8c0 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
1d8d0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1d8e0 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
1d8f0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
1d900 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
1d910 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
1d920 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
1d930 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
1d940 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
1d950 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
1d960 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1d970 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
1d980 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
1d990 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
1d9a0 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
1d9b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
1d9c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1d9d0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1d9e0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1d9f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1da00 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1da10 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1da20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1da30 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1da40 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1da50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1da60 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
1da70 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1da80 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1da90 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1daa0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1dab0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1dac0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
1dad0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1dae0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1daf0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1db00 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1db10 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1db20 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1db30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1db40 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1db50 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1db60 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1db70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1db80 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1db90 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1dba0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1dbb0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1dbc0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1dbd0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1dbe0 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1dbf0 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1dc00 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1dc10 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1dc20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1dc30 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1dc40 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1dc50 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1dc60 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1dc70 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1dc80 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1dc90 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1dca0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1dcb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1dcc0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1dcd0 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1dce0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1dcf0 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1dd00 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1dd10 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
1dd20 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
1dd30 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
1dd40 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
1dd50 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
1dd60 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1dd70 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1dd80 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
1dd90 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
1dda0 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
1ddb0 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
1ddc0 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
1ddd0 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
1dde0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
1ddf0 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
1de00 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1de10 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
1de20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
1de30 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
1de40 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
1de50 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
1de60 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
1de70 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
1de80 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1de90 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
1dea0 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
1deb0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
1dec0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ded0 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
1dee0 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
1def0 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
1df00 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
1df10 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
1df20 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
1df30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
1df40 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
1df50 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
1df60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
1df70 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
1df80 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1df90 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
1dfa0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
1dfb0 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
1dfc0 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
1dfd0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
1dfe0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1dff0 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
1e000 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
1e010 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
1e020 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
1e030 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
1e040 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1e050 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
1e060 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
1e070 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
1e080 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
1e090 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
1e0a0 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
1e0b0 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
1e0c0 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
1e0d0 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
1e0e0 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
1e0f0 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
1e100 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
1e110 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
1e120 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
1e130 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
1e140 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
1e150 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
1e160 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
1e170 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
1e180 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
1e190 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
1e1a0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
1e1b0 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
1e1c0 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
1e1d0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
1e1e0 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
1e1f0 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
1e200 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
1e210 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
1e220 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
1e230 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
1e240 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1e250 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
1e260 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
1e270 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
1e280 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
1e290 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
1e2a0 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
1e2b0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
1e2c0 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
1e2d0 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
1e2e0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
1e2f0 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
1e300 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74  * ^On windows, t
1e310 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
1e320 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
1e330 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
1e340 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
1e350 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
1e360 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
1e370 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
1e380 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
1e390 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
1e3a0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
1e3b0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
1e3c0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
1e3d0 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
1e3e0 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
1e3f0 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
1e400 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
1e410 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
1e420 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
1e430 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1e440 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
1e450 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1e460 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
1e470 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
1e480 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1e490 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
1e4a0 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
1e4b0 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
1e4c0 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
1e4d0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1e4e0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1e4f0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
1e500 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
1e510 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
1e520 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
1e530 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
1e540 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
1e550 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
1e560 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
1e570 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
1e580 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
1e590 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
1e5a0 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
1e5b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e5c0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
1e5d0 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
1e5e0 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
1e5f0 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
1e600 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
1e610 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
1e620 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
1e630 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
1e640 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
1e650 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
1e660 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e670 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
1e680 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
1e690 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
1e6a0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
1e6b0 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
1e6c0 20 6f 72 0a 2a 2a 20 20 20 20 20 22 72 77 63 22   or.**     "rwc"
1e6d0 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
1e6e0 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
1e6f0 68 65 72 20 76 61 6c 75 65 20 69 73 20 61 6e 20  her value is an 
1e700 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
1e710 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
1e720 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
1e730 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1e740 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
1e750 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
1e760 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
1e770 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1e780 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
1e790 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
1e7a0 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
1e7b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1e7c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2e  e3_prepare_v2().
1e7d0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
1e7e0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
1e7f0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
1e800 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1e810 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1e820 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
1e830 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
1e840 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
1e850 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1e860 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
1e870 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1e880 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
1e890 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
1e8a0 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
1e8b0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
1e8c0 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
1e8d0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1e8e0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
1e8f0 5f 43 52 45 41 54 45 2e 20 5e 49 66 20 73 71 6c  _CREATE. ^If sql
1e900 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1e910 73 20 0a 2a 2a 20 20 20 20 20 75 73 65 64 2c 20  s .**     used, 
1e920 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  it is an error t
1e930 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
1e940 65 20 66 6f 72 20 74 68 65 20 6d 6f 64 65 20 70  e for the mode p
1e950 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
1e960 20 0a 2a 2a 20 20 20 20 20 6c 65 73 73 20 72 65   .**     less re
1e970 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
1e980 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
1e990 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
1e9a0 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 0a  d as the third .
1e9b0 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
1e9c0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
1e9d0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
1e9e0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
1e9f0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
1ea00 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
1ea10 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
1ea20 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
1ea30 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
1ea40 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
1ea50 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
1ea60 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
1ea70 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
1ea80 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
1ea90 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
1eaa0 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
1eab0 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
1eac0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
1ead0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
1eae0 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
1eaf0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1eb00 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
1eb10 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
1eb20 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
1eb30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1eb40 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
1eb50 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
1eb60 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
1eb70 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
1eb80 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
1eb90 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
1eba0 62 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73  behaviour reques
1ebb0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
1ebc0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
1ebd0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
1ebe0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
1ebf0 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
1ec00 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
1ec10 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
1ec20 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
1ec30 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
1ec40 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
1ec50 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
1ec60 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
1ec70 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1ec80 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
1ec90 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
1eca0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
1ecb0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
1ecc0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
1ecd0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
1ece0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
1ecf0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
1ed00 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
1ed10 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
1ed20 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
1ed30 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
1ed40 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
1ed50 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
1ed60 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
1ed70 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
1ed80 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
1ed90 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
1eda0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
1edb0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
1edc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
1edd0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
1ede0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
1edf0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
1ee00 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
1ee10 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1ee20 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
1ee30 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
1ee40 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
1ee50 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
1ee60 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
1ee70 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1ee80 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
1ee90 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
1eea0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1eeb0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
1eec0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
1eed0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
1eee0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
1eef0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
1ef00 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
1ef10 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
1ef20 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
1ef30 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
1ef40 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
1ef50 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
1ef60 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
1ef70 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
1ef80 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
1ef90 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
1efa0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
1efb0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
1efc0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
1efd0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
1efe0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
1eff0 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
1f000 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
1f010 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
1f020 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
1f030 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
1f040 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
1f050 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
1f060 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
1f070 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
1f080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1f090 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
1f0a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
1f0b0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
1f0c0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
1f0d0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
1f0e0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
1f0f0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
1f100 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
1f110 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
1f120 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
1f130 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1f140 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1f150 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
1f160 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
1f170 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
1f180 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
1f190 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
1f1a0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
1f1b0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
1f1c0 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a  ix-nolock <td>.*
1f1d0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
1f1e0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
1f1f0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
1f200 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
1f210 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a  unix-nolock"..**
1f220 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1f230 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
1f240 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
1f250 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
1f260 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
1f270 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
1f280 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
1f290 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
1f2a0 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
1f2b0 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
1f2c0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
1f2d0 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
1f2e0 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
1f2f0 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
1f300 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
1f310 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
1f320 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
1f330 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
1f340 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
1f350 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
1f360 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
1f370 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
1f380 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
1f390 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
1f3a0 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
1f3b0 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
1f3c0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
1f3d0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
1f3e0 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
1f3f0 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
1f400 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
1f410 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
1f420 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
1f430 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
1f440 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
1f450 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
1f460 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
1f470 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
1f480 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
1f490 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
1f4a0 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
1f4b0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
1f4c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
1f4d0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1f4e0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1f4f0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1f500 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1f510 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1f520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1f530 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1f540 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1f550 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1f560 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1f570 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1f580 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1f590 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1f5a0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1f5b0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1f5c0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1f5d0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1f5e0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1f5f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1f600 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1f610 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
1f620 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1f630 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1f640 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1f650 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1f660 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1f670 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1f680 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1f690 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1f6a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1f6b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1f6c0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1f6d0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1f6e0 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1f6f0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1f700 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1f710 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1f720 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1f730 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1f740 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1f750 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1f760 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1f770 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1f780 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1f790 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1f7a0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1f7b0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1f7c0 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1f7d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1f7e0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1f7f0 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1f800 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1f810 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
1f820 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
1f830 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
1f840 2a 2a 20 54 68 69 73 20 69 73 20 61 20 75 74 69  ** This is a uti
1f850 6c 69 74 79 20 72 6f 75 74 69 6e 65 2c 20 75 73  lity routine, us
1f860 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
1f870 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
1f880 74 20 63 68 65 63 6b 73 0a 2a 2a 20 74 6f 20 73  t checks.** to s
1f890 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
1f8a0 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
1f8b0 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
1f8c0 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
1f8d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
1f8e0 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
1f8f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
1f900 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
1f910 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 46 69  r..**.** The zFi
1f920 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1f930 69 73 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  is the filename 
1f940 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
1f950 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a  nto the xOpen().
1f960 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 56  ** method of a V
1f970 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1f980 6e 2e 20 20 54 68 65 20 7a 50 61 72 61 6d 20 61  n.  The zParam a
1f990 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
1f9a0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 71 75  ame of the.** qu
1f9b0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 77 65  ery parameter we
1f9c0 20 73 65 65 6b 2e 20 20 54 68 69 73 20 72 6f 75   seek.  This rou
1f9d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1f9e0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 7a 50   value of the zP
1f9f0 61 72 61 6d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  aram.** paramete
1fa00 72 20 69 66 20 69 74 20 65 78 69 73 74 73 2e 20  r if it exists. 
1fa10 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
1fa20 72 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74  r does not exist
1fa30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  , this routine.*
1fa40 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
1fa50 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1fa60 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
1fa70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
1fa80 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f  s function is no
1fa90 74 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  t a pointer that
1faa0 20 53 51 4c 69 74 65 0a 2a 2a 20 70 61 73 73 65   SQLite.** passe
1fab0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
1fac0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
1fad0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
1fae0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  f this routine.*
1faf0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  * is undefined a
1fb00 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
1fb10 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
1fb20 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1fb30 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
1fb40 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
1fb50 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
1fb60 2a 7a 50 61 72 61 6d 29 3b 0a 0a 0a 2f 2a 0a 2a  *zParam);.../*.*
1fb70 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1fb80 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1fb90 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1fba0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1fbb0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1fbc0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1fbd0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1fbe0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1fbf0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1fc00 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1fc10 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1fc20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1fc30 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1fc40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fc50 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1fc60 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1fc70 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1fc80 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1fc90 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1fca0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1fcb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1fcc0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1fcd0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1fce0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1fcf0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1fd00 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1fd10 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1fd20 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1fd30 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1fd40 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1fd50 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1fd60 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1fd70 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1fd80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1fd90 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1fda0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1fdb0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1fdc0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1fdd0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1fde0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1fdf0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1fe00 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1fe10 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1fe20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1fe30 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1fe40 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1fe50 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1fe60 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1fe70 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1fe80 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1fe90 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1fea0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1feb0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1fec0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1fed0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1fee0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1fef0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1ff00 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1ff10 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1ff20 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1ff30 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1ff40 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1ff50 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1ff60 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1ff70 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1ff80 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1ff90 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1ffa0 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1ffb0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1ffc0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1ffd0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1ffe0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1fff0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
20000 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
20010 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
20020 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
20030 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
20040 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
20050 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
20060 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
20070 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
20080 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
20090 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
200a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
200b0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
200c0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
200d0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
200e0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
200f0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
20100 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
20110 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
20120 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
20130 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
20140 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
20150 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
20160 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
20170 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
20180 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
20190 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
201a0 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
201b0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
201c0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
201d0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
201e0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
201f0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
20200 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
20210 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
20220 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
20230 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
20240 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
20250 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
20260 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
20270 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
20280 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
20290 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
202a0 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
202b0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
202c0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
202d0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
202e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
202f0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
20300 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
20310 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
20320 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
20330 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
20340 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
20350 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
20360 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
20370 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
20380 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
20390 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
203a0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
203b0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
203c0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
203d0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
203e0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
203f0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
20400 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
20410 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
20420 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
20430 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
20440 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
20450 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
20460 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
20470 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
20480 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
20490 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
204a0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
204b0 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
204c0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
204d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
204e0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
204f0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
20500 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
20510 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20520 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
20530 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
20540 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
20550 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
20560 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
20570 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
20580 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
20590 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
205a0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
205b0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
205c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
205d0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
205e0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
205f0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
20600 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
20610 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
20620 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
20630 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
20640 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
20650 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
20660 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
20670 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
20680 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
20690 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
206a0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
206b0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
206c0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
206d0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
206e0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
206f0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
20700 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
20710 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
20720 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20730 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
20740 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
20750 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
20760 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
20770 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
20780 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
20790 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
207a0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
207b0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
207c0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
207d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
207e0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
207f0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
20800 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
20810 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
20820 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
20830 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
20840 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
20850 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
20860 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
20870 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
20880 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
20890 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
208a0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
208b0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
208c0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
208d0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
208e0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
208f0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
20900 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
20910 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
20920 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
20930 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
20940 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
20950 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
20960 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
20970 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
20980 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
20990 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
209a0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
209b0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
209c0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
209d0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
209e0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
209f0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
20a00 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
20a10 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
20a20 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
20a30 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
20a40 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
20a50 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
20a60 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
20a70 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
20a80 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
20a90 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
20aa0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
20ab0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
20ac0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
20ad0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
20ae0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
20af0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
20b00 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
20b10 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
20b20 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
20b30 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
20b40 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
20b50 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
20b60 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
20b70 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
20b80 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
20b90 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
20ba0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
20bb0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
20bc0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
20bd0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
20be0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
20bf0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
20c00 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
20c10 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
20c20 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
20c30 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
20c40 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
20c50 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
20c60 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
20c70 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
20c80 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
20c90 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
20ca0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
20cb0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
20cc0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
20cd0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
20ce0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
20cf0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
20d00 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
20d10 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
20d20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
20d30 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
20d40 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
20d50 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
20d60 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
20d70 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
20d80 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
20d90 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
20da0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
20db0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
20dc0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
20dd0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
20de0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
20df0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
20e00 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
20e10 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
20e20 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
20e30 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
20e40 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
20e50 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
20e60 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
20e70 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
20e80 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
20e90 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
20ea0 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
20eb0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
20ec0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
20ed0 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
20ee0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
20ef0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
20f00 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
20f10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
20f20 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
20f30 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
20f40 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
20f50 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
20f60 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
20f70 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
20f80 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
20f90 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
20fa0 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
20fb0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
20fc0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
20fd0 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
20fe0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
20ff0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
21000 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
21010 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
21020 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
21030 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
21040 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
21050 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
21060 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
21070 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
21080 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
21090 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
210a0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
210b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
210c0 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
210d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
210e0 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
210f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
21100 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
21110 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
21120 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
21130 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
21140 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
21150 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
21160 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
21170 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
21180 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
21190 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
211a0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
211b0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
211c0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
211d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
211e0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
211f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
21200 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
21210 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21220 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
21230 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
21240 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
21250 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
21260 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
21270 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
21280 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
21290 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
212a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
212b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
212c0 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
212d0 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
212e0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
212f0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
21300 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
21310 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
21320 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
21330 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
21340 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
21350 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
21360 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
21370 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
21380 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
21390 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
213a0 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
213b0 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
213c0 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
213d0 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
213e0 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
213f0 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
21400 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
21410 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
21420 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
21430 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
21440 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
21450 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
21460 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
21470 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
21480 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
21490 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
214a0 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
214b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
214c0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
214d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
214e0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
214f0 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
21500 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
21510 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
21520 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
21530 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
21540 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
21550 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
21560 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
21570 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21580 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
21590 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
215a0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
215b0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
215c0 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
215d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
215e0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
215f0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
21600 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
21610 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
21620 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
21630 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
21640 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
21650 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
21660 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
21670 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
21680 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
21690 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
216a0 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
216b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
216c0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
216d0 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
216e0 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
216f0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
21700 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
21710 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
21720 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
21730 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
21740 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
21750 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
21760 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
21770 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
21780 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
21790 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
217a0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
217b0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
217c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
217d0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
217e0 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
217f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
21800 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
21810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
21820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
21830 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
21840 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
21850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21860 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
21870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21880 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
21890 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
218a0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
218b0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
218c0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
218d0 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
218e0 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
218f0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
21900 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
21910 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
21920 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
21930 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
21940 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
21950 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
21960 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
21970 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
21980 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
21990 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
219a0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
219b0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
219c0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
219d0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
219e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
219f0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
21a00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21a10 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
21a20 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
21a30 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
21a40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
21a50 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
21a60 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
21a70 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
21a80 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
21a90 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
21aa0 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
21ab0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
21ac0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
21ad0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
21ae0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
21af0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
21b00 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
21b10 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
21b20 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
21b30 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
21b40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
21b50 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
21b60 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
21b70 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
21b80 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
21b90 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
21ba0 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
21bb0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
21bc0 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
21bd0 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
21be0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
21bf0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
21c00 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
21c10 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
21c20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
21c30 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
21c40 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
21c50 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
21c60 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
21c70 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
21c80 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
21c90 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
21ca0 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
21cb0 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
21cc0 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
21cd0 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
21ce0 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
21cf0 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
21d00 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
21d10 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
21d20 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
21d30 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
21d40 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
21d50 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
21d60 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
21d70 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
21d80 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
21d90 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
21da0 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
21db0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
21dc0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
21dd0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
21de0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
21df0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
21e00 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20  s as this saves 
21e10 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69  SQLite from havi
21e20 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20  ng to.** make a 
21e30 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75  copy of the inpu
21e40 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
21e50 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
21e60 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
21e70 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
21e80 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
21e90 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
21ea0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
21eb0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
21ec0 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
21ed0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
21ee0 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
21ef0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
21f00 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
21f10 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
21f20 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
21f30 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
21f40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
21f50 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
21f60 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
21f70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21f80 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
21f90 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
21fa0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
21fb0 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
21fc0 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
21fd0 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
21fe0 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
21ff0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
22000 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
22010 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
22020 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
22030 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
22040 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
22050 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
22060 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
22070 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
22080 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
22090 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
220a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
220b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
220c0 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
220d0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
220e0 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
220f0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
22100 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
22110 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
22120 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
22130 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
22140 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
22150 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
22160 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
22170 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
22180 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22190 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
221a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
221b0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
221c0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
221d0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
221e0 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
221f0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
22200 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
22210 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
22220 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
22230 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
22240 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
22250 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
22260 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
22270 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22280 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
22290 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
222a0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
222b0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
222c0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
222d0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
222e0 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
222f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22300 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
22310 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
22320 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
22330 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
22340 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
22350 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
22360 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
22370 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
22380 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
22390 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
223a0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
223b0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
223c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
223d0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
223e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
223f0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
22400 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  again..** </li>.
22410 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
22420 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
22430 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
22440 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
22450 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
22460 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
22470 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
22480 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
22490 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
224a0 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
224b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
224c0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
224d0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
224e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
224f0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
22500 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
22510 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
22520 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
22530 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
22540 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
22550 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
22560 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
22570 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
22580 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
22590 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
225a0 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
225b0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
225c0 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
225d0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
225e0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
225f0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
22600 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
22610 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
22620 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
22630 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
22640 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
22650 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
22660 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
22670 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
22680 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
22690 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
226a0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
226b0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
226c0 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
226d0 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
226e0 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
226f0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
22700 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
22710 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
22720 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
22730 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22740 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
22750 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
22760 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
22770 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
22780 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
22790 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
227a0 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
227b0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
227c0 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
227d0 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
227e0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
227f0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
22800 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
22810 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
22820 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
22830 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
22840 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
22850 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
22860 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
22870 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
22880 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f  d..** the .** </
22890 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
228a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
228b0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
228c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
228d0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
228e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
228f0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
22900 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
22910 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
22920 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
22930 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
22940 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
22950 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
22960 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
22970 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
22980 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
22990 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
229a0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
229b0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
229c0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
229d0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
229e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
229f0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
22a00 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
22a10 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
22a20 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
22a30 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
22a40 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
22a50 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
22a60 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
22a70 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
22a80 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
22a90 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
22aa0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
22ab0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
22ac0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
22ad0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
22ae0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
22af0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
22b00 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
22b10 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
22b20 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
22b30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
22b40 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
22b50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
22b60 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
22b70 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
22b80 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
22b90 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
22ba0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
22bb0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
22bc0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
22bd0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
22be0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
22bf0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
22c00 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
22c10 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
22c20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
22c30 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
22c40 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
22c50 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
22c60 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
22c70 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
22c80 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
22c90 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
22ca0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
22cb0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
22cc0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
22cd0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
22ce0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
22cf0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
22d00 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
22d10 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
22d20 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
22d30 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
22d40 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
22d50 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
22d60 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
22d70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
22d80 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
22d90 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
22da0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
22db0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
22dc0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
22dd0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
22de0 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
22df0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
22e00 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
22e10 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
22e20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
22e30 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
22e40 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
22e50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
22e60 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
22e70 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
22e80 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
22e90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22ea0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
22eb0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
22ec0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
22ed0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
22ee0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
22ef0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22f00 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
22f10 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
22f20 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
22f30 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
22f40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
22f50 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
22f60 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
22f70 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
22f80 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
22f90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
22fa0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
22fb0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
22fc0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
22fd0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
22fe0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
22ff0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
23000 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
23010 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
23020 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
23030 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
23040 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
23050 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
23060 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
23070 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
23080 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
23090 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
230a0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
230b0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
230c0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
230d0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
230e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
230f0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
23100 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
23110 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
23120 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
23130 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
23140 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
23150 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
23160 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
23170 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
23180 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
23190 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
231a0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
231b0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
231c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
231d0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
231e0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
231f0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
23200 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
23210 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
23220 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
23230 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
23240 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
23250 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
23260 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
23270 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
23280 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
23290 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
232a0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
232b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
232c0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
232d0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
232e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
232f0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
23300 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
23310 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
23320 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
23330 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
23340 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
23350 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
23360 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
23370 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
23380 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
23390 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
233a0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
233b0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
233c0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
233d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
233e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
233f0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
23400 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
23410 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
23420 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
23430 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
23440 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23450 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
23460 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
23470 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23480 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
23490 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
234a0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
234b0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
234c0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
234d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
234e0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
234f0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
23500 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
23510 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
23520 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
23530 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
23540 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
23550 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
23560 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
23570 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
23580 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
23590 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
235a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
235b0 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
235c0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
235d0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
235e0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
235f0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
23600 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
23610 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
23620 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
23630 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
23640 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
23650 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
23660 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
23670 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
23680 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
23690 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
236a0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
236b0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
236c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
236d0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
236e0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
236f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
23700 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
23710 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
23720 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
23730 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
23740 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
23750 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
23760 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
23770 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
23780 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
23790 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
237a0 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
237b0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
237c0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
237d0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
237e0 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
237f0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
23800 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
23810 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
23820 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
23830 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
23840 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
23850 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
23860 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
23870 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
23880 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
23890 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
238a0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
238b0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
238c0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
238d0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
238e0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
238f0 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
23900 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
23910 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
23920 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
23930 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
23940 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
23950 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
23960 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
23970 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
23980 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
23990 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
239a0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
239b0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
239c0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
239d0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
239e0 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
239f0 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
23a00 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
23a10 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
23a20 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
23a30 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
23a40 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
23a50 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
23a60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
23a70 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
23a80 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
23a90 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
23aa0 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
23ab0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
23ac0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
23ad0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
23ae0 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
23af0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
23b00 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
23b10 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
23b20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
23b30 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
23b40 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
23b50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23b60 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
23b70 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
23b80 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
23b90 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
23ba0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
23bb0 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
23bc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
23bd0 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
23be0 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
23bf0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
23c00 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
23c10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
23c20 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
23c30 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
23c40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
23c50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23c60 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
23c70 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
23c80 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
23c90 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
23ca0 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
23cb0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
23cc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
23cd0 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
23ce0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
23cf0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
23d00 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
23d10 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
23d20 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
23d30 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
23d40 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
23d50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
23d60 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
23d70 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
23d80 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
23d90 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
23da0 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
23db0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
23dc0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
23dd0 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
23de0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
23df0 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
23e00 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
23e10 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
23e20 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
23e30 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
23e40 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
23e50 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
23e60 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
23e70 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
23e80 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
23e90 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
23ea0 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
23eb0 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
23ec0 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
23ed0 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
23ee0 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
23ef0 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
23f00 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
23f10 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
23f20 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
23f30 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
23f40 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
23f50 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
23f60 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  g}.**.** ^(In th
23f70 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
23f80 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
23f90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23fa0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
23fb0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
23fc0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
23fd0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
23fe0 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
23ff0 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
24000 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
24010 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
24020 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
24030 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
24040 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
24050 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
24060 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
24070 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
24080 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
24090 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
240a0 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
240b0 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
240c0 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
240d0 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
240e0 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
240f0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
24100 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
24110 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
24120 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
24130 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
24140 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
24150 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
24160 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
24170 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
24180 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
24190 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
241a0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
241b0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
241c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
241d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
241e0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
241f0 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
24200 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
24210 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
24220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
24230 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
24240 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
24250 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
24260 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
24270 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
24280 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
24290 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
242a0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
242b0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
242c0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
242d0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
242e0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
242f0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
24300 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
24310 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
24320 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
24330 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
24340 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
24350 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
24360 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
24370 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
24380 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
24390 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
243a0 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
243b0 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
243c0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
243d0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
243e0 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
243f0 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
24400 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
24410 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
24420 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
24430 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
24440 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
24450 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
24460 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
24470 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
24480 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
24490 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
244a0 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
244b0 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
244c0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
244d0 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
244e0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
244f0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
24500 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
24510 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
24520 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
24530 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
24540 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
24550 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
24560 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
24570 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
24580 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
24590 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
245a0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
245b0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
245c0 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
245d0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
245e0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
245f0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
24600 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
24610 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
24620 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24630 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
24640 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74  _bind_text16() t
24650 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74  hen that paramet
24660 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
24670 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
24680 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
24690 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
246a0 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
246b0 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
246c0 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
246d0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
246e0 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
246f0 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
24700 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
24710 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
24720 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
24730 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
24740 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
24750 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
24760 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
24770 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
24780 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
24790 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
247a0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
247b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
247c0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
247d0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
247e0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
247f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
24800 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
24810 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
24820 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
24830 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
24840 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
24850 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
24860 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
24870 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
24880 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
24890 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
248a0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
248b0 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
248c0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73  if the call to s
248d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
248e0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  (),.** sqlite3_b
248f0 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73  ind_text(), or s
24900 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24910 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a  16() fails.  .**
24920 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
24930 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
24940 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
24950 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
24960 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
24970 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
24980 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
24990 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
249a0 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
249b0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
249c0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
249d0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
249e0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
249f0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
24a00 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
24a10 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
24a20 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
24a30 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
24a40 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
24a50 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
24a60 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
24a70 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
24a80 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
24a90 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
24aa0 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
24ab0 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
24ac0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
24ad0 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
24ae0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
24af0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
24b00 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
24b10 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
24b20 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
24b30 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
24b40 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
24b50 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
24b60 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
24b70 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
24b80 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
24b90 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
24ba0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
24bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
24bc0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
24bd0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
24be0 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
24bf0 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
24c00 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
24c10 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
24c20 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
24c30 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
24c40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
24c50 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
24c60 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
24c70 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
24c80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24c90 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
24ca0 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
24cb0 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
24cc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
24cd0 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
24ce0 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
24cf0 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
24d00 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
24d10 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
24d20 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
24d30 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
24d40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
24d50 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
24d60 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
24d70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
24d80 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
24d90 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
24da0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
24db0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
24dc0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
24dd0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
24de0 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
24df0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24e00 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
24e10 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
24e20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
24e30 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
24e40 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
24e50 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
24e60 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
24e70 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
24e80 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
24e90 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
24ea0 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
24eb0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
24ec0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
24ed0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
24ee0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
24ef0 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
24f00 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
24f10 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
24f20 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
24f30 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
24f40 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
24f50 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
24f60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
24f70 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
24f80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
24f90 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
24fa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
24fb0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
24fc0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
24fd0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
24fe0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
24ff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25000 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
25010 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
25020 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
25030 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
25040 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
25050 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
25060 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
25070 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
25080 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
25090 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
250a0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
250b0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
250c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
250d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
250e0 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
250f0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
25100 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
25110 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
25120 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25130 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
25140 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
25150 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
25160 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
25170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25180 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
25190 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
251a0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
251b0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
251c0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
251d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
251e0 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
251f0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
25200 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
25210 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
25220 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
25230 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
25240 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
25250 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
25260 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
25270 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
25280 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
25290 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
252a0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
252b0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
252c0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
252d0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
252e0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
252f0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
25300 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
25310 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
25320 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
25330 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
25340 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
25350 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
25360 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
25370 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
25380 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
25390 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
253a0 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
253b0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
253c0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
253d0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
253e0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
253f0 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
25400 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
25410 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
25420 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
25430 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
25440 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
25450 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
25460 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
25470 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
25480 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
25490 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
254a0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
254b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
254c0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
254d0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
254e0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
254f0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
25500 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
25510 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25520 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
25530 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
25540 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
25550 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
25560 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
25570 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25580 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
25590 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
255a0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
255b0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
255c0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
255d0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
255e0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
255f0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
25600 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
25610 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
25620 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
25630 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
25640 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
25650 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
25660 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
25670 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
25680 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
25690 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
256a0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
256b0 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
256c0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
256d0 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
256e0 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
256f0 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
25700 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
25710 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
25720 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
25730 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
25740 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
25750 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
25760 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
25770 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
25780 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
25790 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
257a0 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
257b0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
257c0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
257d0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
257e0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
257f0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
25800 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
25810 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
25820 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
25830 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
25840 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25850 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
25860 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
25870 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
25880 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
25890 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
258a0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
258b0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
258c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
258d0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
258e0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
258f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
25900 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
25910 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
25920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
25930 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
25940 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
25950 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
25960 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
25970 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
25980 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
25990 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
259a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
259b0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
259c0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
259d0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
259e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
259f0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
25a00 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
25a10 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
25a20 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
25a30 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
25a40 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
25a50 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
25a60 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
25a70 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
25a80 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
25a90 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
25aa0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
25ab0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
25ac0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
25ad0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
25ae0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25af0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
25b00 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
25b10 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
25b20 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
25b30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25b40 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
25b50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
25b60 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
25b70 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
25b80 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
25b90 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
25ba0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
25bb0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
25bc0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
25bd0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
25be0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
25bf0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
25c00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
25c10 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
25c20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
25c30 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
25c40 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
25c50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
25c60 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
25c70 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
25c80 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
25c90 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
25ca0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
25cb0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
25cc0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
25cd0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
25ce0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
25cf0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
25d00 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
25d10 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
25d20 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
25d30 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
25d40 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
25d50 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
25d60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
25d70 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
25d80 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
25d90 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
25da0 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
25db0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
25dc0 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
25dd0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
25de0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
25df0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
25e00 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
25e10 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
25e20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25e30 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
25e40 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
25e50 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
25e60 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
25e70 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
25e80 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
25e90 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
25ea0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
25eb0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
25ec0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
25ed0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
25ee0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25ef0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
25f00 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
25f10 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
25f20 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
25f30 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
25f40 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
25f50 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
25f60 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
25f70 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
25f80 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
25f90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25fa0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
25fb0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
25fc0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
25fd0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
25fe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
25ff0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
26000 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
26010 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
26020 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
26030 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
26040 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
26050 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
26060 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26070 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
26080 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
26090 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
260a0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
260b0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
260c0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
260d0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
260e0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
260f0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
26100 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
26110 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
26120 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
26130 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26140 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
26150 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
26160 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
26170 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
26180 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
26190 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
261a0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
261b0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
261c0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
261d0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
261e0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
261f0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
26200 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
26210 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
26220 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
26230 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
26240 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
26250 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
26260 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
26270 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
26280 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
26290 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
262a0 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
262b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
262c0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
262d0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
262e0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
262f0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
26300 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
26310 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
26320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26330 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
26340 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
26350 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
26360 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
26370 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
26380 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26390 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
263a0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
263b0 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
263c0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
263d0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
263e0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
263f0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
26400 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
26410 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
26420 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
26430 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
26440 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
26450 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
26460 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
26470 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
26480 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
26490 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
264a0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
264b0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
264c0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
264d0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
264e0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
264f0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
26500 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
26510 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
26520 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
26530 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
26540 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
26550 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
26560 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
26570 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
26580 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26590 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
265a0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
265b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
265c0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
265d0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
265e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
265f0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
26600 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
26610 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26620 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
26630 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
26640 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
26650 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
26660 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
26670 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
26680 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
26690 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
266a0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
266b0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
266c0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
266d0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
266e0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
266f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
26700 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
26710 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
26720 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26730 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
26740 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
26750 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
26760 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
26770 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
26780 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
26790 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
267a0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
267b0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
267c0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
267d0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
267e0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
267f0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
26800 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
26810 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
26820 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
26830 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
26840 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
26850 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
26860 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
26870 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
26880 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
26890 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
268a0 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
268b0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
268c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
268d0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
268e0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
268f0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
26900 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
26910 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
26920 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
26930 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
26940 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
26950 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
26960 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
26970 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
26980 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
26990 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
269a0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
269b0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
269c0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
269d0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
269e0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
269f0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
26a00 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
26a10 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
26a20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
26a30 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
26a40 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
26a50 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
26a60 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
26a70 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
26a80 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
26a90 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
26aa0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
26ab0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
26ac0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26ad0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
26ae0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
26af0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
26b00 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
26b10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
26b20 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
26b30 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
26b40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
26b50 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
26b60 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
26b70 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
26b80 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
26b90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26ba0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
26bb0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
26bc0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
26bd0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
26be0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
26bf0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
26c00 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
26c10 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
26c20 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
26c30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
26c40 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
26c50 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
26c60 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
26c70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
26c80 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
26c90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
26ca0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
26cb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
26cc0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
26cd0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
26ce0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
26cf0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
26d00 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
26d10 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
26d20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
26d30 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
26d40 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
26d50 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
26d60 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
26d70 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
26d80 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
26d90 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
26da0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
26db0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26dc0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
26dd0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
26de0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
26df0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
26e00 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
26e10 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
26e20 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
26e30 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
26e40 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
26e50 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
26e60 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
26e70 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
26e80 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
26e90 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
26ea0 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
26eb0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
26ec0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
26ed0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
26ee0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
26ef0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
26f00 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
26f10 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
26f20 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
26f30 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
26f40 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
26f50 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
26f60 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
26f70 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
26f80 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
26f90 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
26fa0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
26fb0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
26fc0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
26fd0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
26fe0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
26ff0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
27000 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
27010 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
27020 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
27030 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
27040 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
27050 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
27060 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
27070 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
27080 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
27090 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
270a0 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
270b0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
270c0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
270d0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
270e0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
270f0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
27100 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
27110 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
27120 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
27130 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
27140 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
27150 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
27160 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
27170 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
27180 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
27190 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
271a0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
271b0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
271c0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
271d0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
271e0 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
271f0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
27200 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
27210 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
27220 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27230 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
27240 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
27250 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
27260 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
27270 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
27280 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
27290 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
272a0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
272b0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
272c0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
272d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
272e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
272f0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
27300 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
27310 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
27320 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
27330 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
27340 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
27350 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
27360 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
27370 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
27380 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
27390 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
273a0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
273b0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
273c0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
273d0 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
273e0 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
273f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
27400 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
27410 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
27420 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
27430 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
27440 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
27450 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
27460 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
27470 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
27480 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
27490 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
274a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
274b0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
274c0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
274d0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
274e0 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
274f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
27500 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
27510 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
27520 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
27530 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
27540 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
27550 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
27560 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
27570 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
27580 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
27590 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
275a0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
275b0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
275c0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
275d0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
275e0 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
275f0 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
27600 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
27610 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
27620 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
27630 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
27640 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
27650 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
27660 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
27670 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
27680 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
27690 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
276a0 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
276b0 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
276c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
276d0 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
276e0 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
276f0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
27700 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
27710 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
27720 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
27730 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
27740 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
27750 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
27760 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
27770 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
27780 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
27790 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
277a0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
277b0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
277c0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
277d0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
277e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
277f0 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
27800 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
27810 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
27820 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
27830 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
27840 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
27850 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
27860 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
27870 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27880 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
27890 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
278a0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
278b0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
278c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
278d0 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
278e0 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
278f0 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
27900 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
27910 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
27920 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
27930 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
27940 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
27950 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
27960 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
27970 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
27980 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
27990 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
279a0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
279b0 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
279c0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
279d0 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
279e0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
279f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
27a00 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
27a10 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
27a20 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
27a30 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
27a40 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
27a50 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
27a60 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
27a70 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
27a80 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
27a90 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
27aa0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
27ab0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
27ac0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
27ad0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
27ae0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
27af0 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
27b00 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
27b10 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
27b20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
27b30 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
27b40 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
27b50 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
27b60 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
27b70 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
27b80 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
27b90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
27ba0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
27bb0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
27bc0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
27bd0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
27be0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
27bf0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
27c00 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
27c10 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
27c20 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
27c30 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
27c40 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
27c50 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
27c60 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
27c70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27c80 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
27c90 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
27ca0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
27cb0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
27cc0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
27cd0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
27ce0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
27cf0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
27d00 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
27d10 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
27d20 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
27d30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27d40 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
27d50 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
27d60 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
27d70 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
27d80 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
27d90 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
27da0 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
27db0 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
27dc0 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
27dd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
27de0 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
27df0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
27e00 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
27e10 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
27e20 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
27e30 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
27e40 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
27e50 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
27e60 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
27e70 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
27e80 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
27e90 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
27ea0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
27eb0 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
27ec0 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
27ed0 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
27ee0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
27ef0 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
27f00 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
27f10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
27f20 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
27f30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27f40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
27f50 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
27f60 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
27f70 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
27f80 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
27f90 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
27fa0 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
27fb0 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
27fc0 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
27fd0 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
27fe0 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
27ff0 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
28000 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
28010 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
28020 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
28030 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
28040 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
28050 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
28060 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
28070 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
28080 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
28090 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
280a0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
280b0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
280c0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
280d0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
280e0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
280f0 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
28100 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
28110 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
28120 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
28130 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
28140 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
28150 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
28160 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28170 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
28180 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
28190 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
281a0 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
281b0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
281c0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
281d0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
281e0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
281f0 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
28200 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
28210 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
28220 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
28230 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
28240 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
28250 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
28260 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
28270 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
28280 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28290 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
282a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
282b0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
282c0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
282d0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
282e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
282f0 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
28300 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
28310 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
28320 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
28330 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
28340 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
28350 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
28360 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
28370 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
28380 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
28390 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
283a0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
283b0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
283c0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
283d0 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a  a result set.**.
283e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
283f0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
28400 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28410 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
28420 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
28430 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
28440 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
28450 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28460 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
28470 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28480 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
28490 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
284a0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
284b0 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
284c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
284d0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
284e0 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
284f0 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
28500 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
28510 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
28520 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
28530 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
28540 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
28550 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
28560 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
28570 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
28580 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
28590 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
285a0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
285b0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
285c0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
285d0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
285e0 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
285f0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
28600 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
28610 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
28620 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
28630 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
28640 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
28650 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
28660 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
28670 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
28680 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
28690 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
286a0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
286b0 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
286c0 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
286d0 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
286e0 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
286f0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
28700 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
28710 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
28720 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
28730 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
28740 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
28750 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28760 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
28770 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
28780 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
28790 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
287a0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
287b0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
287c0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
287d0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
287e0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
287f0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
28800 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
28810 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
28820 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
28830 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
28840 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
28850 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
28860 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
28870 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
28880 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
28890 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
288a0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
288b0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
288c0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
288d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
288e0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
288f0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
28900 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
28910 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
28920 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
28930 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
28940 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
28950 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
28960 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
28970 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
28980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
28990 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
289a0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
289b0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
289c0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
289d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
289e0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
289f0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
28a00 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
28a10 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
28a20 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
28a30 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
28a40 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
28a50 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
28a60 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
28a70 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
28a80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
28a90 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
28aa0 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
28ab0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
28ac0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
28ad0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
28ae0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
28af0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
28b00 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
28b10 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
28b20 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
28b30 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
28b40 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
28b50 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
28b60 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
28b70 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
28b80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28b90 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
28ba0 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
28bb0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
28bc0 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
28bd0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
28be0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28bf0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
28c00 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
28c10 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
28c20 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
28c30 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
28c40 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
28c50 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
28c60 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
28c70 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
28c80 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
28c90 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
28ca0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
28cb0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
28cc0 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
28cd0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
28ce0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
28cf0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
28d00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
28d10 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
28d20 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
28d30 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
28d40 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
28d50 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
28d60 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
28d70 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
28d80 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
28d90 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
28da0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
28db0 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
28dc0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
28dd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
28de0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
28df0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
28e00 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
28e10 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
28e20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28e30 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
28e40 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
28e50 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
28e60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
28e70 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
28e80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28e90 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
28ea0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
28eb0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
28ec0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
28ed0 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
28ee0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
28ef0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
28f00 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
28f10 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
28f20 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
28f30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28f40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
28f50 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
28f60 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
28f70 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
28f80 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
28f90 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
28fa0 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
28fb0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
28fc0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
28fd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
28fe0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
28ff0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
29000 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
29010 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
29020 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
29030 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
29040 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
29050 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
29060 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
29070 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
29080 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
29090 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
290a0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
290b0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
290c0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
290d0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
290e0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
290f0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
29100 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
29110 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
29120 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
29130 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
29140 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
29150 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
29160 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
29170 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
29180 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
29190 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
291a0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
291b0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
291c0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
291d0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
291e0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
291f0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
29200 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
29210 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
29220 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
29230 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
29240 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
29250 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
29260 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
29270 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
29280 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
29290 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
292a0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
292b0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
292c0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
292d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
292e0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
292f0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
29300 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
29310 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
29320 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
29330 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
29340 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
29350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29360 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
29370 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
29380 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
29390 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
293a0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
293b0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
293c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
293d0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
293e0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
293f0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
29400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
29410 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
29420 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
29430 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
29440 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
29450 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
29460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
29470 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
29480 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
29490 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
294a0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
294b0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
294c0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
294d0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
294e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
294f0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
29500 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
29510 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
29520 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
29530 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
29540 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
29550 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
29560 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
29570 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29580 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
29590 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
295a0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
295b0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
295c0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
295d0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
295e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
295f0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
29600 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
29610 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
29620 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
29630 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
29640 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
29650 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
29660 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29670 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
29680 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29690 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
296a0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
296b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
296c0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
296d0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
296e0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
296f0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
29700 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
29710 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
29720 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
29730 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
29740 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
29750 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
29760 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
29770 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
29780 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
29790 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
297a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
297b0 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
297c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
297d0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
297e0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
297f0 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
29800 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
29810 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
29820 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29830 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
29840 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
29850 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
29860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65  .**.** ^The obje
29870 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
29880 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
29890 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
298a0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
298b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
298c0 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
298d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
298e0 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
298f0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
29900 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
29910 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
29920 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
29930 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
29940 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
29950 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
29960 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
29970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
29980 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
29990 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
299a0 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
299b0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
299c0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
299d0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
299e0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
299f0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
29a00 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
29a10 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
29a20 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
29a30 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
29a40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
29a50 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
29a60 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
29a70 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
29a80 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
29a90 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
29aa0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
29ab0 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
29ac0 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
29ad0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
29ae0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
29af0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
29b00 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
29b10 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
29b20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
29b30 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
29b40 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
29b50 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
29b60 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
29b70 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
29b80 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
29b90 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
29ba0 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
29bb0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
29bc0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
29bd0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
29be0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
29bf0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
29c00 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
29c10 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
29c20 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
29c30 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
29c40 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
29c50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
29c60 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
29c70 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
29c80 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
29c90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
29ca0 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
29cb0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
29cc0 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
29cd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
29ce0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
29cf0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
29d00 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
29d10 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
29d20 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
29d30 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
29d40 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
29d50 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
29d60 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
29d70 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
29d80 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
29d90 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
29da0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
29db0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
29dc0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
29dd0 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74  rom float to int
29de0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
29df0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
29e00 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
29e10 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
29e20 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
29e30 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
29e40 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
29e50 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41  td> Same as FLOA
29e60 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  T->TEXT.** <tr><
29e70 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
29e80 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
29e90 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   Use atoi().** <
29ea0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
29eb0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
29ec0 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a  <td> Use atof().
29ed0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
29ee0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
29ef0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
29f00 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
29f10 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
29f20 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
29f30 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
29f40 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   use atoi().** <
29f50 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
29f60 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
29f70 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
29f80 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
29f90 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
29fa0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
29fb0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
29fc0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
29fd0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
29fe0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
29ff0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
2a000 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
2a010 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
2a020 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
2a030 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
2a040 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
2a050 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
2a060 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
2a070 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
2a080 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
2a090 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
2a0a0 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
2a0b0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
2a0c0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
2a0d0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
2a0e0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
2a0f0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
2a100 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
2a110 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
2a120 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
2a130 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2a140 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
2a150 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
2a160 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2a170 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
2a180 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2a190 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
2a1a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2a1b0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
2a1c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a1d0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
2a1e0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
2a1f0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
2a200 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
2a210 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
2a220 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
2a230 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
2a240 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2a250 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2a260 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
2a270 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2a280 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
2a290 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2a2a0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2a2b0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
2a2c0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
2a2d0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
2a2e0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
2a2f0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
2a300 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
2a310 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
2a320 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
2a330 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2a340 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
2a350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2a360 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2a370 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2a380 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2a390 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2a3a0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
2a3b0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2a3c0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
2a3d0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2a3e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2a3f0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2a400 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2a410 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2a420 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2a430 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2a440 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
2a450 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2a460 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
2a470 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
2a480 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
2a490 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
2a4a0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
2a4b0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
2a4c0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
2a4d0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
2a4e0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2a4f0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
2a500 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
2a510 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
2a520 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
2a530 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
2a540 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
2a550 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
2a560 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
2a570 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
2a580 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
2a590 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
2a5a0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
2a5b0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
2a5c0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
2a5d0 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
2a5e0 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
2a5f0 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
2a600 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
2a610 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
2a620 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
2a630 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
2a640 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2a650 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2a660 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
2a670 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2a680 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2a690 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2a6a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2a6b0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2a6c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2a6d0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2a6e0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2a6f0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
2a700 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2a710 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
2a720 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2a730 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2a740 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
2a750 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
2a760 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
2a770 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2a780 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
2a790 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2a7a0 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
2a7b0 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
2a7c0 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
2a7d0 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
2a7e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a7f0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
2a800 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2a810 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
2a820 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
2a830 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
2a840 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
2a850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2a860 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2a870 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
2a880 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
2a890 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a8a0 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
2a8b0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
2a8c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a8d0 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
2a8e0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2a8f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2a900 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
2a910 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
2a920 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
2a930 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2a940 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
2a950 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
2a960 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
2a970 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2a980 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2a990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2a9a0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
2a9b0 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
2a9c0 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
2a9d0 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
2a9e0 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
2a9f0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
2aa00 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
2aa10 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
2aa20 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
2aa30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2aa40 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
2aa50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
2aa60 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
2aa70 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
2aa80 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
2aa90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2aaa0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
2aab0 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
2aac0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
2aad0 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
2aae0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
2aaf0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
2ab00 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
2ab10 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
2ab20 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
2ab30 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2ab40 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
2ab50 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
2ab60 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
2ab70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
2ab80 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
2ab90 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
2aba0 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
2abb0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2abc0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
2abd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2abe0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2abf0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
2ac00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ac10 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2ac20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ac30 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
2ac40 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
2ac50 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
2ac60 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
2ac70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2ac80 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2ac90 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
2aca0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2acb0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
2acc0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
2acd0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
2ace0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2acf0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
2ad00 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2ad10 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
2ad20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2ad30 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
2ad40 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2ad50 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2ad60 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2ad70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2ad80 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
2ad90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2ada0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
2adb0 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
2adc0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
2add0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2ade0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2adf0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
2ae00 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2ae10 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
2ae20 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2ae30 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
2ae40 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
2ae50 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
2ae60 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
2ae70 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2ae80 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
2ae90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
2aea0 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
2aeb0 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
2aec0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
2aed0 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
2aee0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
2aef0 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
2af00 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
2af10 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
2af20 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2af30 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
2af40 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
2af50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2af60 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
2af70 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
2af80 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
2af90 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
2afa0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2afb0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2afc0 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
2afd0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
2afe0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
2aff0 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
2b000 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2b010 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
2b020 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
2b030 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
2b040 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
2b050 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
2b060 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2b070 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
2b080 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
2b090 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
2b0a0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
2b0b0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
2b0c0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
2b0d0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
2b0e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
2b0f0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
2b100 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
2b110 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
2b120 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
2b130 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
2b140 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
2b150 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
2b160 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
2b170 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
2b180 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
2b190 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
2b1a0 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
2b1b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2b1c0 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
2b1d0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2b1e0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2b1f0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2b200 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
2b210 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2b220 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2b230 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2b240 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
2b250 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
2b260 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
2b270 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
2b280 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
2b290 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
2b2a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
2b2b0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
2b2c0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2b2d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2b2e0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
2b2f0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2b300 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2b310 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
2b320 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
2b330 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
2b340 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2b350 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
2b360 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
2b370 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
2b380 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
2b390 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
2b3a0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
2b3b0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
2b3c0 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
2b3d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2b3e0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2b3f0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
2b400 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
2b410 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
2b420 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2b430 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
2b440 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
2b450 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2b460 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2b470 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
2b480 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b490 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
2b4a0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
2b4b0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
2b4c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
2b4d0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2b4e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b4f0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2b500 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b510 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
2b520 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
2b530 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
2b540 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
2b550 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
2b560 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
2b570 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
2b580 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
2b590 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2b5a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
2b5b0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2b5c0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2b5d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2b5e0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2b5f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b600 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
2b610 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
2b620 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2b630 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
2b640 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2b650 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2b660 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2b670 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
2b680 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2b690 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
2b6a0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
2b6b0 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
2b6c0 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
2b6d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
2b6e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2b6f0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
2b700 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2b710 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
2b720 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
2b730 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
2b740 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
2b750 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
2b760 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
2b770 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
2b780 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2b790 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
2b7a0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
2b7b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2b7c0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54  ctions}.**.** ^T
2b7d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
2b7e0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
2b7f0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
2b800 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2b810 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
2b820 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
2b830 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2b840 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
2b850 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
2b860 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
2b870 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2b880 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
2b890 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
2b8a0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
2b8b0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
2b8c0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2b8d0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
2b8e0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2b8f0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
2b900 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
2b910 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
2b920 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
2b930 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
2b940 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
2b950 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
2b960 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2b970 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
2b980 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
2b990 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
2b9a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b9b0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
2b9c0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
2b9d0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
2b9e0 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
2b9f0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
2ba00 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
2ba10 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
2ba20 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
2ba30 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2ba40 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
2ba50 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
2ba60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ba70 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
2ba80 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2ba90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2baa0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
2bab0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
2bac0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
2bad0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
2bae0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
2baf0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
2bb00 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
2bb10 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
2bb20 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
2bb30 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
2bb40 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
2bb50 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
2bb60 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
2bb70 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
2bb80 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
2bb90 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
2bba0 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
2bbb0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
2bbc0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
2bbd0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
2bbe0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
2bbf0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2bc00 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
2bc10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2bc20 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
2bc30 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
2bc40 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2bc50 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
2bc60 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2bc70 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
2bc80 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
2bc90 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
2bca0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2bcb0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
2bcc0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
2bcd0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
2bce0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
2bcf0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
2bd00 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2bd10 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
2bd20 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
2bd30 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
2bd40 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
2bd50 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
2bd60 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
2bd70 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2bd80 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
2bd90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
2bda0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
2bdb0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
2bdc0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
2bdd0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
2bde0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
2bdf0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
2be00 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
2be10 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53  meters.  Every S
2be20 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
2be30 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
2be40 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
2be50 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  ** with UTF-8, U
2be60 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
2be70 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
2be80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2be90 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
2bea0 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
2beb0 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
2bec0 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70  another.  ^An ap
2bed0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a  plication may.**
2bee0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2bef0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2bf00 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
2bf10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2bf20 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
2bf30 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
2bf40 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
2bf50 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
2bf60 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
2bf70 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
2bf80 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2bf90 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2bfa0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
2bfb0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
2bfc0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
2bfd0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
2bfe0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
2bff0 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
2c000 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
2c010 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
2c020 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2c030 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
2c040 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a   care what text.
2c050 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  ** encoding is u
2c060 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
2c070 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
2c080 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f  ould be [SQLITE_
2c090 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ANY]..**.** ^(Th
2c0a0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
2c0b0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
2c0c0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
2c0d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2c0e0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
2c0f0 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
2c100 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
2c110 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
2c120 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
2c130 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2c140 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
2c150 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
2c160 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
2c170 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
2c180 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
2c190 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
2c1a0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
2c1b0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2c1c0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2c1d0 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
2c1e0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2c1f0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2c200 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
2c210 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
2c220 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
2c230 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
2c240 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
2c250 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
2c260 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
2c270 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2c280 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2c290 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2c2a0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
2c2b0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
2c2c0 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
2c2d0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
2c2e0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
2c2f0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
2c300 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2c310 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
2c320 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
2c330 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
2c340 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
2c350 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
2c360 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2c370 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2c380 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
2c390 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
2c3a0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
2c3b0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
2c3c0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2c3d0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
2c3e0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
2c3f0 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
2c400 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
2c410 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
2c420 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
2c430 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
2c440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
2c450 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
2c460 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
2c470 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
2c480 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
2c490 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c4a0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
2c4b0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
2c4c0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
2c4d0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
2c4e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
2c4f0 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
2c500 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
2c510 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
2c520 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
2c530 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2c540 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
2c550 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
2c560 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2c570 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c580 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
2c590 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
2c5a0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
2c5b0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2c5c0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2c5d0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
2c5e0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
2c5f0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
2c600 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
2c610 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
2c620 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
2c630 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
2c640 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
2c650 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
2c660 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2c670 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
2c680 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
2c690 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
2c6a0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
2c6b0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
2c6c0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2c6d0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
2c6e0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
2c6f0 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
2c700 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
2c710 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2c720 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2c730 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
2c740 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
2c750 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
2c760 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2c770 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
2c780 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
2c790 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
2c7a0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
2c7b0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2c7c0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2c7d0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
2c7e0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
2c7f0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2c800 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
2c810 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
2c820 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
2c830 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
2c840 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
2c850 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
2c860 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
2c870 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
2c880 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
2c890 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
2c8a0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
2c8b0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
2c8c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c8d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
2c8e0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
2c8f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2c900 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
2c910 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
2c920 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
2c930 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
2c940 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
2c950 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
2c960 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2c970 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
2c980 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
2c990 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2c9a0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
2c9b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
2c9c0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
2c9d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2c9e0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
2c9f0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2ca00 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2ca10 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2ca20 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2ca30 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2ca40 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2ca50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2ca60 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2ca70 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2ca80 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2ca90 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2caa0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2cab0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2cac0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2cad0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2cae0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2caf0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2cb00 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
2cb10 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2cb20 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2cb30 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2cb40 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2cb50 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2cb60 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2cb70 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2cb80 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2cb90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2cba0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2cbb0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2cbc0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2cbd0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
2cbe0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2cbf0 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
2cc00 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2cc10 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
2cc20 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2cc30 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2cc40 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2cc50 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2cc60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2cc70 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2cc80 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2cc90 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2cca0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2ccb0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2ccc0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2ccd0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2cce0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
2ccf0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
2cd00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cd10 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
2cd20 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2cd30 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
2cd40 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
2cd50 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
2cd60 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
2cd70 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
2cd80 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
2cd90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2cda0 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
2cdb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2cdc0 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
2cdd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2cde0 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
2cdf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2ce00 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
2ce10 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
2ce20 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
2ce30 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
2ce40 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
2ce50 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2ce60 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
2ce70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2ce80 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
2ce90 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
2cea0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2ceb0 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
2cec0 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
2ced0 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
2cee0 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
2cef0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2cf00 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
2cf10 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
2cf20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
2cf30 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
2cf40 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
2cf50 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
2cf60 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
2cf70 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
2cf80 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
2cf90 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
2cfa0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
2cfb0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
2cfc0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
2cfd0 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
2cfe0 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
2cff0 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
2d000 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
2d010 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
2d020 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79  ll you what they
2d030 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
2d040 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
2d050 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45  ECATED.SQLITE_DE
2d060 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2d070 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d080 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
2d090 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  text*);.SQLITE_D
2d0a0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2d0b0 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
2d0c0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
2d0d0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2d0e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
2d0f0 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
2d100 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
2d110 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
2d120 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2d130 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
2d140 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
2d150 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2d160 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
2d170 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
2d180 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
2d190 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2d1a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
2d1b0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
2d1c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
2d1d0 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
2d1e0 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
2d1f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d200 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
2d210 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
2d220 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
2d230 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
2d240 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
2d250 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2d260 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
2d270 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
2d280 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
2d290 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
2d2a0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
2d2b0 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
2d2c0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2d2d0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
2d2e0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
2d2f0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
2d300 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
2d310 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
2d320 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
2d330 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2d340 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2d350 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2d360 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
2d370 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
2d380 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2d390 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2d3a0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
2d3b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2d3c0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
2d3d0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
2d3e0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
2d3f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d400 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2d410 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
2d420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d430 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
2d440 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2d450 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
2d460 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2d470 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
2d480 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
2d490 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
2d4a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2d4b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2d4c0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
2d4d0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
2d4e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d4f0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
2d500 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
2d510 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
2d520 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
2d530 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
2d540 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
2d550 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
2d560 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
2d570 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2d580 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
2d590 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
2d5a0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2d5b0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
2d5c0 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
2d5d0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
2d5e0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
2d5f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d600 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
2d610 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
2d620 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
2d630 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
2d640 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
2d650 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
2d660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d670 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
2d680 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
2d690 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
2d6a0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
2d6b0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
2d6c0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
2d6d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2d6e0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
2d6f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2d700 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
2d710 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
2d720 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
2d730 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
2d740 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
2d750 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
2d760 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
2d770 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2d780 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
2d790 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
2d7a0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
2d7b0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
2d7c0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
2d7d0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
2d7e0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
2d7f0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
2d800 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
2d810 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
2d820 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
2d830 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
2d840 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
2d850 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
2d860 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
2d870 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
2d880 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
2d890 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
2d8a0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
2d8b0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
2d8c0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
2d8d0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
2d8e0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
2d8f0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
2d900 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2d910 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
2d920 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
2d930 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
2d940 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
2d950 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
2d960 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
2d970 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
2d980 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
2d990 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
2d9a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d9b0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
2d9c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2d9d0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
2d9e0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
2d9f0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
2da00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2da10 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
2da20 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2da30 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
2da40 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2da50 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2da60 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
2da70 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2da80 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2da90 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2daa0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
2dab0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2dac0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
2dad0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
2dae0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
2daf0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2db00 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2db10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2db20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2db30 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
2db40 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2db50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2db60 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
2db70 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
2db80 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
2db90 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2dba0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2dbb0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
2dbc0 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
2dbd0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
2dbe0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
2dbf0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2dc00 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
2dc10 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2dc20 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
2dc30 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2dc40 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2dc50 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
2dc60 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2dc70 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2dc80 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
2dc90 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2dca0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2dcb0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
2dcc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2dcd0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2dce0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
2dcf0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2dd00 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2dd10 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
2dd20 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
2dd30 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
2dd40 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
2dd50 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
2dd60 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
2dd70 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
2dd80 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
2dd90 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
2dda0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
2ddb0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
2ddc0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
2ddd0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
2dde0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
2ddf0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2de00 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
2de10 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
2de20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
2de30 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
2de40 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
2de50 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
2de60 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
2de70 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
2de80 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
2de90 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
2dea0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
2deb0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
2dec0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2ded0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2dee0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
2def0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
2df00 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
2df10 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
2df20 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
2df30 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
2df40 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
2df50 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
2df60 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
2df70 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
2df80 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
2df90 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
2dfa0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
2dfb0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
2dfc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
2dfd0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
2dfe0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
2dff0 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
2e000 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
2e010 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
2e020 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
2e030 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
2e040 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
2e050 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
2e060 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
2e070 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
2e080 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
2e090 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2e0a0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
2e0b0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
2e0c0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
2e0d0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
2e0e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e0f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2e100 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
2e110 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
2e120 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69  L pointer if N i
2e130 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f  s.** less than o
2e140 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
2e150 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  or if a memory a
2e160 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
2e170 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
2e180 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
2e190 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
2e1a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2e1b0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
2e1c0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
2e1d0 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
2e1e0 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
2e1f0 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
2e200 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
2e210 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
2e220 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2e230 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2e240 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
2e250 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
2e260 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2e270 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
2e280 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
2e290 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
2e2a0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  n.)^.**.** ^SQLi
2e2b0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2e2c0 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
2e2d0 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
2e2e0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2e2f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
2e300 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
2e310 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
2e320 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
2e330 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
2e340 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
2e350 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
2e360 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
2e370 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
2e380 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
2e390 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
2e3a0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
2e3b0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
2e3c0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
2e3d0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
2e3e0 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
2e3f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2e400 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2e410 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2e420 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2e430 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
2e440 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2e450 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
2e460 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2e470 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2e480 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2e490 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2e4a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2e4b0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2e4c0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2e4d0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
2e4e0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2e4f0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2e500 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
2e510 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
2e520 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
2e530 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
2e540 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2e550 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e560 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2e570 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2e580 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2e590 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2e5a0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2e5b0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2e5c0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2e5d0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
2e5e0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2e5f0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2e600 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2e610 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2e620 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e630 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2e640 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
2e650 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
2e660 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2e670 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2e680 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2e690 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
2e6a0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
2e6b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ^The sqlite3_con
2e6c0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2e6d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2e6e0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2e6f0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
2e700 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2e710 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
2e720 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
2e730 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2e740 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2e750 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2e760 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e770 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2e780 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2e790 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2e7a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2e7b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2e7c0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
2e7d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2e7e0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
2e7f0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
2e800 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
2e810 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
2e820 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  ta.**.** The fol
2e830 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
2e840 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
2e850 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
2e860 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
2e870 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
2e880 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
2e890 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
2e8a0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
2e8b0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
2e8c0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
2e8d0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
2e8e0 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
2e8f0 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
2e900 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
2e910 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
2e920 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
2e930 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
2e940 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
2e950 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
2e960 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
2e970 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
2e980 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
2e990 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
2e9a0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
2e9b0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
2e9c0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2e9d0 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
2e9e0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2e9f0 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
2ea00 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
2ea10 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2ea20 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
2ea30 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
2ea40 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
2ea50 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
2ea60 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
2ea70 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
2ea80 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2ea90 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
2eaa0 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
2eab0 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
2eac0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
2ead0 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
2eae0 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
2eaf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2eb00 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
2eb10 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2eb20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2eb30 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
2eb40 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
2eb50 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2eb60 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
2eb70 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
2eb80 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
2eb90 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2eba0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2ebb0 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  . ^If no metadat
2ebc0 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
2ebd0 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
2ebe0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2ebf0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2ec00 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
2ec10 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
2ec20 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
2ec30 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
2ec40 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
2ec50 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
2ec60 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2ec70 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
2ec80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2ec90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2eca0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2ecb0 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
2ecc0 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
2ecd0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
2ece0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
2ecf0 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
2ed00 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
2ed10 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2ed20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ed30 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
2ed40 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2ed50 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
2ed60 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
2ed70 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
2ed80 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
2ed90 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
2eda0 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  yed..** ^If it i
2edb0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
2edc0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2edd0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2ede0 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
2edf0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
2ee00 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2ee10 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
2ee20 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
2ee30 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
2ee40 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
2ee50 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
2ee60 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
2ee70 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2ee80 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
2ee90 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
2eea0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
2eeb0 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
2eec0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
2eed0 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
2eee0 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
2eef0 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
2ef00 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
2ef10 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72    ^The only guar
2ef20 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
2ef30 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2ef40 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
2ef50 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
2ef60 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
2ef70 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
2ef80 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
2ef90 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
2efa0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
2efb0 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
2efc0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
2efd0 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
2efe0 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
2eff0 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
2f000 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
2f010 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  meters].)^.**.**
2f020 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2f030 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2f040 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2f050 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2f060 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f070 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2f080 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
2f090 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2f0a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2f0b0 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
2f0c0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
2f0d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2f0e0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
2f0f0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
2f100 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f110 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
2f120 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
2f130 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
2f140 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
2f150 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
2f160 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
2f170 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
2f180 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
2f190 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
2f1a0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2f1b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2f1c0 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
2f1d0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
2f1e0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
2f1f0 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
2f200 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2f210 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
2f220 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
2f230 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
2f240 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
2f250 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
2f260 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
2f270 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
2f280 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
2f290 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
2f2a0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
2f2b0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
2f2c0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
2f2d0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
2f2e0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2f2f0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
2f300 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
2f310 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
2f320 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
2f330 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
2f340 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
2f350 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
2f360 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
2f370 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
2f380 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
2f390 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
2f3a0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
2f3b0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
2f3c0 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
2f3d0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2f3e0 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
2f3f0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
2f400 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
2f410 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2f420 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
2f430 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
2f440 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
2f450 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
2f460 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2f470 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
2f480 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
2f490 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
2f4a0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
2f4b0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2f4c0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
2f4d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2f4e0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2f4f0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2f500 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2f510 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
2f520 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
2f530 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2f540 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
2f550 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
2f560 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
2f570 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
2f580 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
2f590 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
2f5a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
2f5b0 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
2f5c0 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
2f5d0 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
2f5e0 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
2f5f0 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
2f600 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2f610 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f620 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2f630 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2f640 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2f650 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2f660 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f670 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
2f680 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
2f690 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
2f6a0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
2f6b0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
2f6c0 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
2f6d0 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
2f6e0 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
2f6f0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
2f700 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f710 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
2f720 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
2f730 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2f740 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f750 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2f760 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
2f770 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
2f780 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
2f790 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
2f7a0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
2f7b0 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
2f7c0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
2f7d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f7e0 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
2f7f0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2f800 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2f810 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f820 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2f830 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
2f840 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
2f850 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
2f860 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2f870 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2f880 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
2f890 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f8a0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
2f8b0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
2f8c0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
2f8d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
2f8e0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
2f8f0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2f900 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
2f910 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
2f920 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
2f930 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
2f940 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
2f950 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f960 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
2f970 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
2f980 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
2f990 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
2f9a0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2f9b0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2f9c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f9d0 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
2f9e0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
2f9f0 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
2fa00 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2fa10 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
2fa20 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
2fa30 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
2fa40 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
2fa50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2fa60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2fa70 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
2fa80 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2fa90 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
2faa0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
2fab0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
2fac0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
2fad0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
2fae0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
2faf0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
2fb00 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2fb10 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2fb20 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
2fb30 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2fb40 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
2fb50 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
2fb60 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
2fb70 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
2fb80 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
2fb90 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
2fba0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
2fbb0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
2fbc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2fbd0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
2fbe0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fbf0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
2fc00 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
2fc10 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2fc20 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
2fc30 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
2fc40 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
2fc50 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
2fc60 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
2fc70 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
2fc80 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
2fc90 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
2fca0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2fcb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2fcc0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
2fcd0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
2fce0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2fcf0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2fd00 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
2fd10 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
2fd20 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
2fd30 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
2fd40 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
2fd50 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
2fd60 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
2fd70 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
2fd80 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
2fd90 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2fda0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
2fdb0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
2fdc0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
2fdd0 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
2fde0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
2fdf0 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
2fe00 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2fe10 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
2fe20 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
2fe30 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
2fe40 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
2fe50 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
2fe60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fe70 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
2fe80 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2fe90 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
2fea0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
2feb0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
2fec0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2fed0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
2fee0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2fef0 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
2ff00 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2ff10 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2ff20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2ff30 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2ff40 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
2ff50 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2ff60 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
2ff70 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
2ff80 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
2ff90 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2ffa0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2ffb0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2ffc0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2ffd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2ffe0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2fff0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
30000 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
30010 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
30020 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
30030 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30040 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
30050 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
30060 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
30070 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
30080 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30090 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
300a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
300b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
300c0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
300d0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
300e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
300f0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
30100 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
30110 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
30120 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
30130 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
30140 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
30150 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30160 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
30170 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
30180 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
30190 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
301a0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
301b0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
301c0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
301d0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
301e0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
301f0 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
30200 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
30210 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
30220 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
30230 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
30240 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
30250 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
30260 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
30270 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
30280 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
30290 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
302a0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
302b0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
302c0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
302d0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
302e0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
302f0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
30300 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
30310 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
30320 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
30330 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
30340 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
30350 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
30360 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
30370 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
30380 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
30390 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
303a0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
303b0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
303c0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
303d0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
303e0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
303f0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
30400 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
30410 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
30420 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
30430 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
30440 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
30450 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
30460 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
30470 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
30480 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
30490 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
304a0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
304b0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
304c0 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
304d0 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
304e0 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
304f0 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
30500 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
30510 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
30520 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
30530 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
30540 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
30550 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
30560 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
30570 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
30580 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
30590 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
305a0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
305b0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
305c0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
305d0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
305e0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
305f0 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
30600 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
30610 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
30620 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
30630 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
30640 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
30650 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
30660 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
30670 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
30680 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
30690 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
306a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
306b0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
306c0 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
306d0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
306e0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
306f0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
30700 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
30710 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
30720 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
30730 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
30740 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
30750 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
30760 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
30770 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
30780 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
30790 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
307a0 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
307b0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
307c0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
307d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
307e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
307f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30800 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
30810 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
30820 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
30830 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
30840 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
30850 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
30860 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
30870 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
30880 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
30890 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
308a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
308b0 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
308c0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
308d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
308e0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
308f0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
30900 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
30910 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30920 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
30930 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
30940 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30950 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
30960 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
30970 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
30980 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
30990 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
309a0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
309b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
309c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
309d0 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
309e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
309f0 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
30a00 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
30a10 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
30a20 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
30a30 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
30a40 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
30a50 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
30a60 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
30a70 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30a80 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
30a90 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
30aa0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
30ab0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30ac0 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
30ad0 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
30ae0 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
30af0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
30b00 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
30b10 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
30b20 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
30b30 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
30b40 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
30b50 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
30b60 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
30b70 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
30b80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30b90 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
30ba0 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
30bb0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
30bc0 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
30bd0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
30be0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  efined..*/.void 
30bf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
30c00 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
30c10 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
30c20 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
30c30 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
30c40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
30c50 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
30c60 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
30c70 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
30c80 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
30c90 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
30ca0 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
30cb0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30cc0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
30cd0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
30ce0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
30cf0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
30d00 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
30d10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30d20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
30d30 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
30d40 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
30d50 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
30d60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
30d70 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
30d80 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
30d90 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30da0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
30db0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
30dc0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30dd0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
30de0 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
30df0 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
30e00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
30e10 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
30e20 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
30e30 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
30e40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
30e50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
30e60 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
30e70 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
30e80 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
30e90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
30ea0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
30eb0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
30ec0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
30ed0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
30ee0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30ef0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
30f00 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
30f10 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
30f20 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
30f30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30f40 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
30f50 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
30f60 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
30f70 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
30f80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30f90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
30fa0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
30fb0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
30fc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30fd0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
30fe0 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
30ff0 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
31000 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
31010 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
31020 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
31030 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
31040 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
31050 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
31060 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31070 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
31080 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
31090 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
310a0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
310b0 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
310c0 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
310d0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
310e0 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
310f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
31100 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
31110 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
31120 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
31130 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
31140 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31150 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
31160 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
31170 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
31180 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
31190 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
311a0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
311b0 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
311c0 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
311d0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
311e0 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
311f0 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
31200 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
31210 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
31220 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
31230 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
31240 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
31250 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
31260 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
31270 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
31280 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
31290 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
312a0 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
312b0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
312c0 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
312d0 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
312e0 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
312f0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
31300 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
31310 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
31320 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
31330 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
31340 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
31350 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
31360 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
31370 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
31380 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
31390 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
313a0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
313b0 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
313c0 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
313d0 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
313e0 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
313f0 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
31400 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
31410 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
31420 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
31430 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
31440 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  t is passed.** t
31450 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
31460 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
31470 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
31480 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  nction callback.
31490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
314a0 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c  h argument, xCal
314b0 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e  lback, is a poin
314c0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ter to the colla
314d0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ting function..*
314e0 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c  * ^Multiple coll
314f0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
31500 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
31510 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  d using the same
31520 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74   name but.** wit
31530 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  h different eTex
31540 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20  tRep parameters 
31550 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
31560 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a  use whichever.**
31570 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
31580 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
31590 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e  unt of data tran
315a0 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  sformation..** ^
315b0 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b  If the xCallback
315c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c   argument is NUL
315d0 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  L then the colla
315e0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
315f0 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57  .** deleted.  ^W
31600 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e  hen all collatin
31610 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69  g functions havi
31620 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
31630 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a   are deleted,.**
31640 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20   that collation 
31650 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61  is no longer usa
31660 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
31670 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
31680 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  on callback is i
31690 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f  nvoked with a co
316a0 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a  py of the pArg .
316b0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ** application d
316c0 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ata pointer and 
316d0 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73  with two strings
316e0 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
316f0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
31700 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72   the eTextRep ar
31710 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c  gument.  The col
31720 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
31730 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a  must return an.*
31740 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69  * integer that i
31750 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  s negative, zero
31760 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a  , or positive.**
31770 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
31780 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
31790 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
317a0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
317b0 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70   second,.** resp
317c0 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c  ectively.  A col
317d0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
317e0 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75  must always retu
317f0 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77  rn the same answ
31800 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20  er.** given the 
31810 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66  same inputs.  If
31820 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c   two or more col
31830 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
31840 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a   are registered.
31850 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63  ** to the same c
31860 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75  ollation name (u
31870 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65  sing different e
31880 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20  TextRep values) 
31890 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74  then all.** must
318a0 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c   give an equival
318b0 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20  ent answer when 
318c0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75  invoked with equ
318d0 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e  ivalent strings.
318e0 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  .** The collatin
318f0 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
31900 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69  obey the followi
31910 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f  ng properties fo
31920 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73  r all.** strings
31930 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a   A, B, and C:.**
31940 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
31950 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d   If A==B then B=
31960 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =A..** <li> If A
31970 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65  ==B and B==C the
31980 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20  n A==C..** <li> 
31990 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42  If A&lt;B THEN B
319a0 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49  &gt;A..** <li> I
319b0 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c  f A&lt;B and B&l
319c0 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e  t;C then A&lt;C.
319d0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
319e0 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66  If a collating f
319f0 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e  unction fails an
31a00 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63  y of the above c
31a10 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
31a20 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67  hat.** collating
31a30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65   function is  re
31a40 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65  gistered and use
31a50 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
31a60 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
31a70 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
31a80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31a90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31aa0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
31ab0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
31ac0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
31ad0 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74  * with the addit
31ae0 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65  ion that the xDe
31af0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
31b00 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72  s invoked on pAr
31b10 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  g when.** the co
31b20 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
31b30 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   is deleted..** 
31b40 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74  ^Collating funct
31b50 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64  ions are deleted
31b60 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
31b70 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
31b80 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74  er.** calls to t
31b90 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
31ba0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
31bb0 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  or when the.** [
31bc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31bd0 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75  ion] is closed u
31be0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
31bf0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ose()]..**.** ^T
31c00 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
31c10 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f  back is <u>not</
31c20 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65  u> called if the
31c30 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65   .** sqlite3_cre
31c40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
31c50 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  () function fail
31c60 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  s.  Applications
31c70 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20   that invoke.** 
31c80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
31c90 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69  ollation_v2() wi
31ca0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44  th a non-NULL xD
31cb0 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20  estroy argument 
31cc0 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b  should .** check
31cd0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
31ce0 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20   and dispose of 
31cf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
31d00 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  data pointer.** 
31d10 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65  themselves rathe
31d20 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67  r than expecting
31d30 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20   SQLite to deal 
31d40 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d  with it for them
31d50 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66  ..** This is dif
31d60 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72  ferent from ever
31d70 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
31d80 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69  nterface.  The i
31d90 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a  nconsistency .**
31da0 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20   is unfortunate 
31db0 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  but cannot be ch
31dc0 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72  anged without br
31dd0 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73  eaking backwards
31de0 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69   .** compatibili
31df0 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ty..**.** See al
31e00 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
31e10 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
31e20 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
31e30 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
31e40 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
31e50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31e60 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
31e70 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
31e80 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
31e90 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
31ea0 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
31eb0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
31ec0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
31ed0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
31ee0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
31ef0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31f00 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
31f10 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
31f20 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
31f30 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
31f40 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
31f50 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
31f60 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
31f70 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
31f80 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
31f90 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
31fa0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
31fb0 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
31fc0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
31fd0 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
31fe0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
31ff0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
32000 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
32010 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
32020 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
32030 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
32040 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
32050 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
32060 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
32070 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
32080 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
32090 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
320a0 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
320b0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
320c0 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
320d0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
320e0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
320f0 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
32100 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32110 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
32120 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
32130 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
32140 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
32150 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
32160 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
32170 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
32180 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
32190 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
321a0 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
321b0 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
321c0 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
321d0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
321e0 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
321f0 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
32200 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
32210 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
32220 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
32230 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
32240 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
32250 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
32260 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
32270 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
32280 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
32290 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
322a0 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
322b0 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
322c0 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
322d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
322e0 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
322f0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
32300 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
32310 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
32320 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
32330 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
32340 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
32350 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
32360 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
32370 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
32380 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
32390 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
323a0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
323b0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
323c0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
323d0 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
323e0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
323f0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
32400 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
32410 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
32420 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
32430 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
32440 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
32450 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
32460 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
32470 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
32480 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
32490 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
324a0 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
324b0 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
324c0 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
324d0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
324e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
324f0 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
32500 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32510 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
32520 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32530 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
32540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
32550 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
32560 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
32570 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
32580 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
32590 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
325a0 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20  t char*).);.int 
325b0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
325c0 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
325d0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
325e0 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
325f0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
32600 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
32610 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20  id*).);..#ifdef 
32620 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43  SQLITE_HAS_CODEC
32630 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
32640 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
32650 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
32660 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
32670 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
32680 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
32690 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
326a0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
326b0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
326c0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
326d0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
326e0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
326f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
32700 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
32710 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
32720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
32730 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
32740 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
32750 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
32760 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
32770 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
32780 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
32790 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
327a0 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
327b0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
327c0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
327d0 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
327e0 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
327f0 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
32800 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
32810 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
32820 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
32830 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
32840 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
32850 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
32860 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
32870 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
32880 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
32890 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
328a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
328b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
328c0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
328d0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
328e0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
328f0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
32900 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
32910 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
32920 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
32930 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62   for a SEE datab
32940 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
32950 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
32960 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74   of the SEE rout
32970 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
32980 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
32990 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20  activate_see(.  
329a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
329b0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
329c0 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
329d0 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
329e0 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
329f0 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a  ENABLE_CEROD./*.
32a00 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
32a10 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
32a20 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61  r a CEROD databa
32a30 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
32a40 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
32a50 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75  of the CEROD rou
32a60 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
32a70 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
32a80 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28  _activate_cerod(
32a90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
32aa0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
32ab0 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
32ac0 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
32ad0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
32ae0 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
32af0 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
32b00 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68  rt Time.**.** Th
32b10 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
32b20 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
32b30 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
32b40 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
32b50 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
32b60 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
32b70 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
32b80 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
32b90 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
32ba0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
32bb0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
32bc0 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
32bd0 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
32be0 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
32bf0 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
32c00 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
32c10 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
32c20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
32c30 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
32c40 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
32c50 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
32c60 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71   actually.** req
32c70 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
32c80 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
32c90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
32ca0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c  .** ^SQLite impl
32cb0 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65  ements this inte
32cc0 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67  rface by calling
32cd0 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a   the xSleep().**
32ce0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
32cf0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
32d00 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66  vfs] object.  If
32d10 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   the xSleep() me
32d20 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64  thod.** of the d
32d30 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f  efault VFS is no
32d40 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f  t implemented co
32d50 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20  rrectly, or not 
32d60 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a  implemented at.*
32d70 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20  * all, then the 
32d80 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
32d90 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20  te3_sleep() may 
32da0 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65  deviate from the
32db0 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20   description.** 
32dc0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
32dd0 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69  paragraphs..*/.i
32de0 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
32df0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
32e00 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
32e10 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
32e20 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
32e30 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  es.**.** ^(If th
32e40 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
32e50 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
32e60 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
32e70 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
32e80 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
32e90 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
32ea0 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
32eb0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
32ec0 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
32ed0 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
32ee0 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65  built-in [sqlite
32ef0 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20  3_vfs | VFS].** 
32f00 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69  will be placed i
32f10 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79  n that directory
32f20 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61  .)^  ^If this va
32f30 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
32f40 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
32f50 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
32f60 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
32f70 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
32f80 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
32f90 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
32fa0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
32fb0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
32fc0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
32fd0 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  in more than one
32fe0 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20  .** thread at a 
32ff0 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74  time.  It is not
33000 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
33010 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
33020 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64  iable.** if a [d
33030 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33040 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65  on] is being use
33050 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  d at the same ti
33060 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65  me in a separate
33070 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  .** thread..** I
33080 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
33090 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
330a0 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
330b0 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
330c0 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
330d0 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
330e0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
330f0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
33100 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61  ve been called a
33110 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  nd that this var
33120 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63  iable remain unc
33130 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61  hanged.** therea
33140 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  fter..**.** ^The
33150 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
33160 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d  ectory pragma] m
33170 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  ay modify this v
33180 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73  ariable and caus
33190 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74  e.** it to point
331a0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
331b0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
331c0 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72  3_malloc].  ^Fur
331d0 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65  thermore,.** the
331e0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
331f0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61  ectory pragma] a
33200 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68  lways assumes th
33210 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a  at any string.**
33220 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
33230 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  ble points to is
33240 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
33250 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
33260 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
33270 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d  c] and the pragm
33280 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f  a may attempt to
33290 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72   free that memor
332a0 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  y.** using [sqli
332b0 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65  te3_free]..** He
332c0 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72  nce, if this var
332d0 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65  iable is modifie
332e0 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68  d directly, eith
332f0 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a  er it should be.
33300 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20  ** made NULL or 
33310 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
33320 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
33330 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
33340 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73  alloc].** or els
33350 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  e the use of the
33360 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
33370 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73  ectory pragma] s
33380 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64  hould be avoided
33390 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
333a0 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
333b0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
333c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
333d0 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d  : Test For Auto-
333e0 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b  Commit Mode.** K
333f0 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f  EYWORDS: {autoco
33400 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  mmit mode}.**.**
33410 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
33420 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69  t_autocommit() i
33430 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33440 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
33450 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
33460 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
33470 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
33480 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
33490 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
334a0 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f  tively.  ^Autoco
334b0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
334c0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e  by default..** ^
334d0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
334e0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
334f0 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
33500 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  nt..** ^Autocomm
33510 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
33520 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
33530 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
33540 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
33550 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
33560 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
33570 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
33580 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
33590 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
335a0 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69   (errors includi
335b0 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d  ng [SQLITE_FULL]
335c0 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  , [SQLITE_IOERR]
335d0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ,.** [SQLITE_NOM
335e0 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  EM], [SQLITE_BUS
335f0 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  Y], and [SQLITE_
33600 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e  INTERRUPT]) then
33610 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74   the.** transact
33620 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c  ion might be rol
33630 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
33640 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c  ically.  The onl
33650 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64  y way to.** find
33660 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c   out whether SQL
33670 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
33680 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
33690 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
336a0 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
336b0 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
336c0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
336d0 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
336e0 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74   changes the aut
336f0 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f  ocommit status o
33700 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
33710 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  * connection whi
33720 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
33730 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e  is running, then
33740 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
33750 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
33760 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
33770 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
33780 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
33790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
337a0 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48  d The Database H
337b0 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61  andle Of A Prepa
337c0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
337d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
337e0 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72  _db_handle inter
337f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
33800 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33810 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
33820 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65   to which a [pre
33830 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33840 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20   belongs.  ^The 
33850 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33860 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  tion].** returne
33870 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f  d by sqlite3_db_
33880 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61  handle is the sa
33890 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
338a0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74  nection].** that
338b0 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61   was the first a
338c0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
338d0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
338e0 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f  re_v2()] call (o
338f0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  r its variants) 
33900 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f  that was used to
33910 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73  .** create the s
33920 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
33930 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a  first place..*/.
33940 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
33950 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
33960 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
33970 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75  * CAPI3REF: Retu
33980 72 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20  rn The Filename 
33990 46 6f 72 20 41 20 44 61 74 61 62 61 73 65 20 43  For A Database C
339a0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
339b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
339c0 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e  filename(D,N) in
339d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
339e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
339f0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63  ilename.** assoc
33a00 69 61 74 65 64 20 77 69 74 68 20 64 61 74 61 62  iated with datab
33a10 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74  ase N of connect
33a20 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69  ion D.  ^The mai
33a30 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  n database file.
33a40 2a 2a 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20  ** has the name 
33a50 22 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72  "main".  If ther
33a60 65 20 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64  e is no attached
33a70 20 64 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74   database N on t
33a80 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
33a90 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20  onnection D, or 
33aa0 69 66 20 64 61 74 61 62 61 73 65 20 4e 20 69 73  if database N is
33ab0 20 61 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20   a temporary or 
33ac0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
33ad0 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55  se, then.** a NU
33ae0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
33af0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
33b00 68 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75  he filename retu
33b10 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
33b20 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74  ction is the out
33b30 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46  put of the.** xF
33b40 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68  ullPathname meth
33b50 6f 64 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e  od of the [VFS].
33b60 20 20 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64    ^In other word
33b70 73 2c 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  s, the filename.
33b80 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62  ** will be an ab
33b90 73 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c  solute pathname,
33ba0 20 65 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c   even if the fil
33bb0 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f  ename used.** to
33bc0 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
33bd0 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61  se originally wa
33be0 73 20 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74  s a URI or relat
33bf0 69 76 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f  ive pathname..*/
33c00 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
33c10 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65  ite3_db_filename
33c20 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f  (sqlite3 *db, co
33c30 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
33c40 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
33c50 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65  REF: Find the ne
33c60 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
33c70 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ement.**.** ^Thi
33c80 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
33c90 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
33ca0 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
33cb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
33cc0 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
33cd0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
33ce0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33cf0 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49  ection] pDb.  ^I
33d00 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a  f pStmt is NULL.
33d10 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74  ** then this int
33d20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
33d30 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
33d40 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73  first prepared s
33d50 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f  tatement.** asso
33d60 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
33d70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33d80 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f  ion pDb.  ^If no
33d90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
33da0 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73  ent.** satisfies
33db0 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20   the conditions 
33dc0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
33dd0 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
33de0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74  ..**.** The [dat
33df0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33e00 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61  ] pointer D in a
33e10 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
33e20 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
33e30 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20  ,S)] must refer 
33e40 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  to an open datab
33e50 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
33e60 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75  n and in particu
33e70 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  lar must not be 
33e80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
33e90 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  */.sqlite3_stmt 
33ea0 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  *sqlite3_next_st
33eb0 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c  mt(sqlite3 *pDb,
33ec0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70   sqlite3_stmt *p
33ed0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
33ee0 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
33ef0 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
33f00 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
33f10 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
33f20 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
33f30 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
33f40 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
33f50 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
33f60 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
33f70 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
33f80 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c  ion is [COMMIT |
33f90 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20   committed]..** 
33fa0 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
33fb0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
33fc0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
33fd0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
33fe0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
33ff0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34000 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
34010 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34020 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
34030 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
34040 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
34050 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
34060 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
34070 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
34080 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20   is [ROLLBACK | 
34090 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a  rolled back]..**
340a0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
340b0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
340c0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
340d0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
340e0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
340f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34100 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
34110 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67  en..** ^The pArg
34120 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
34130 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  sed through to t
34140 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  he callback..** 
34150 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
34160 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
34170 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  k function retur
34180 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20  ns non-zero,.** 
34190 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
341a0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
341b0 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
341c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
341d0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43  _commit_hook(D,C
341e0 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ,P) and sqlite3_
341f0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
34200 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  C,P) functions.*
34210 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61  * return the P a
34220 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
34230 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f   previous call o
34240 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
34250 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  ion.** on the sa
34260 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
34270 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e  nection] D, or N
34280 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66  ULL for.** the f
34290 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61  irst call for ea
342a0 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44  ch function on D
342b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d  ..**.** The comm
342c0 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20  it and rollback 
342d0 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61  hook callbacks a
342e0 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  re not reentrant
342f0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
34300 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
34310 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
34320 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
34330 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
34340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34350 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
34360 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
34370 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
34380 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
34390 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
343a0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
343b0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
343c0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
343d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
343e0 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
343f0 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
34400 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
34410 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
34420 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
34430 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69 6e  Note that runnin
34440 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 20  g any other SQL 
34450 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c  statements, incl
34460 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74 61  uding SELECT sta
34470 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d  tements,.** or m
34480 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73  erely calling [s
34490 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
344a0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
344b0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d  3_step()] will m
344c0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
344d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
344e0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
344f0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
34500 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
34510 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72  .**.** ^Register
34520 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74  ing a NULL funct
34530 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65  ion disables the
34540 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
34550 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69   ^When the commi
34560 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
34570 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
34580 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49  zero, the [COMMI
34590 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  T].** operation 
345a0 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f  is allowed to co
345b0 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e  ntinue normally.
345c0 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74    ^If the commit
345d0 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73   hook.** returns
345e0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
345f0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20  the [COMMIT] is 
34600 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
34610 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20   [ROLLBACK]..** 
34620 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  ^The rollback ho
34630 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ok is invoked on
34640 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74   a rollback that
34650 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20   results from a 
34660 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72  commit.** hook r
34670 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72  eturning non-zer
34680 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f  o, just as it wo
34690 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20  uld be with any 
346a0 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a  other rollback..
346b0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
346c0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
346d0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
346e0 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
346f0 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65  ve been.** rolle
34700 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
34710 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
34720 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
34730 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
34740 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
34750 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
34760 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
34770 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54   to occur..** ^T
34780 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
34790 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
347a0 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
347b0 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
347c0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
347d0 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
347e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
347f0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
34800 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
34810 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
34820 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
34830 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  face..*/.void *s
34840 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
34850 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
34860 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
34870 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
34880 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
34890 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
348a0 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
348b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
348c0 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
348d0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
348e0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
348f0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
34900 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
34910 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
34920 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
34930 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
34940 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34950 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
34960 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
34970 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
34980 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
34990 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
349a0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
349b0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  ed..** ^Any call
349c0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
349d0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
349e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
349f0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
34a00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34a10 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
34a20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
34a30 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
34a40 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
34a50 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
34a60 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
34a70 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
34a80 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
34a90 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
34aa0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
34ab0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
34ac0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
34ad0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
34ae0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
34af0 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63  k()..** ^The sec
34b00 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
34b10 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
34b20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
34b30 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
34b40 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
34b50 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
34b60 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
34b70 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
34b80 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
34b90 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
34ba0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
34bb0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
34bc0 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
34bd0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
34be0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
34bf0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
34c00 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
34c10 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
34c20 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20  ..** ^The final 
34c30 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
34c40 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
34c50 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
34c60 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66   ^In the case of
34c70 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
34c80 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
34c90 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
34ca0 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
34cb0 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65  .** ^(The update
34cc0 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
34cd0 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
34ce0 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
34cf0 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
34d00 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
34d10 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
34d20 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a  sequence).)^.**.
34d30 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65  ** ^In the curre
34d40 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
34d50 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
34d60 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
34d70 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
34d80 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
34d90 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
34da0 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
34db0 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
34dc0 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
34dd0 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65  se.  ^Nor is the
34de0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
34df0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
34e00 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
34e10 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
34e20 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
34e30 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
34e40 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
34e50 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
34e60 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
34e70 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
34e80 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
34e90 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
34ea0 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
34eb0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
34ec0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
34ed0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
34ee0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34ef0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
34f00 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
34f10 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
34f20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
34f30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34f40 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
34f50 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
34f60 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
34f70 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
34f80 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
34f90 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
34fa0 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
34fb0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
34fc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
34fd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
34fe0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
34ff0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
35000 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
35010 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
35020 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
35030 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
35040 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35050 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
35060 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  ,C,P) function.*
35070 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  * returns the P 
35080 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
35090 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a  e previous call.
350a0 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
350b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
350c0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
350d0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
350e0 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a   call on D..**.*
350f0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
35100 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
35110 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
35120 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
35130 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
35140 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  es..*/.void *sql
35150 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
35160 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
35170 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
35180 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
35190 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
351a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
351b0 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
351c0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
351d0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
351e0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
351f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
35200 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a  ared cache}.**.*
35210 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
35220 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
35230 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
35240 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
35250 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
35260 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
35270 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61  ures between [da
35280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35290 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  n | connections]
352a0 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
352b0 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e  database. Sharin
352c0 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
352d0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
352e0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61  true.** and disa
352f0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
35300 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e  ment is false.)^
35310 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68  .**.** ^Cache sh
35320 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
35330 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f   and disabled fo
35340 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
35350 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ess..** This is 
35360 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
35370 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
35380 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
35390 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
353a0 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
353b0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
353c0 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
353d0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
353e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63  .**.** ^(The cac
353f0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
35400 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
35410 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
35420 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
35430 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
35440 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
35450 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
35460 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
35470 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
35480 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
35490 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
354a0 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
354b0 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
354c0 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
354d0 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
354e0 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a  re opened.)^.**.
354f0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
35500 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
35510 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
35520 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65  cache was enable
35530 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
35540 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
35550 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  An [error code] 
35560 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
35570 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rwise.)^.**.** ^
35580 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
35590 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
355a0 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
355b0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
355c0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
355d0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
355e0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
355f0 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
35600 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
35610 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
35620 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
35630 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51  * See Also:  [SQ
35640 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68  Lite Shared-Cach
35650 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73  e Mode].*/.int s
35660 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
35670 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
35680 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35690 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65  : Attempt To Fre
356a0 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a  e Heap Memory.**
356b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
356c0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
356d0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
356e0 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62  mpts to free N b
356f0 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20  ytes.** of heap 
35700 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
35710 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
35720 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tial memory allo
35730 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20  cations.** held 
35740 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
35750 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72  library.   Memor
35760 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20  y used to cache 
35770 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65  database.** page
35780 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72  s to improve per
35790 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65  formance is an e
357a0 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73  xample of non-es
357b0 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a  sential memory..
357c0 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** ^sqlite3_rele
357d0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
357e0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
357f0 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
35800 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63  y freed,.** whic
35810 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
35820 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  or less than the
35830 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
35840 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
35850 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
35860 79 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  y() routine is a
35870 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67   no-op returning
35880 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69   zero.** if SQLi
35890 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c  te is not compil
358a0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
358b0 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
358c0 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a  NAGEMENT]..**.**
358d0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
358e0 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d  te3_db_release_m
358f0 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20  emory()].*/.int 
35900 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
35910 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a  memory(int);../*
35920 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 72  .** CAPI3REF: Fr
35930 65 65 20 4d 65 6d 6f 72 79 20 55 73 65 64 20 42  ee Memory Used B
35940 79 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  y A Database Con
35950 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
35960 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 73 68  he sqlite3_db_sh
35970 72 69 6e 6b 28 44 29 20 69 6e 74 65 72 66 61 63  rink(D) interfac
35980 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72  e attempts to fr
35990 65 65 20 61 73 20 6d 75 63 68 20 68 65 61 70 0a  ee as much heap.
359a0 2a 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70 6f 73  ** memory as pos
359b0 73 69 62 6c 65 20 66 72 6f 6d 20 64 61 74 61 62  sible from datab
359c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
359d0 2e 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  . Unlike the.** 
359e0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
359f0 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74 65 72  _memory()] inter
35a00 66 61 63 65 2c 20 74 68 69 73 20 69 6e 74 65 72  face, this inter
35a10 66 61 63 65 20 69 73 20 65 66 66 65 63 74 20 65  face is effect e
35a20 76 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 6e  ven.** when then
35a30 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
35a40 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
35a50 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
35a60 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69  option is.** omi
35a70 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tted..**.** See 
35a80 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72  also: [sqlite3_r
35a90 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
35aa0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35ab0 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  db_release_memor
35ac0 79 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  y(sqlite3*);../*
35ad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d  .** CAPI3REF: Im
35ae0 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20  pose A Limit On 
35af0 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20  Heap Size.**.** 
35b00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66  ^The sqlite3_sof
35b10 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
35b20 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
35b30 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74  and/or queries t
35b40 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74  he.** soft limit
35b50 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
35b60 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
35b70 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
35b80 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
35b90 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76 65  * ^SQLite strive
35ba0 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20 6d  s to keep heap m
35bb0 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 6f  emory utilizatio
35bc0 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74  n below the soft
35bd0 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62   heap.** limit b
35be0 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 6e  y reducing the n
35bf0 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 68  umber of pages h
35c00 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65 20  eld in the page 
35c10 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 70  cache.** as heap
35c20 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20 61   memory usages a
35c30 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c 69  pproaches the li
35c40 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66  mit..** ^The sof
35c50 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
35c60 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 65  "soft" because e
35c70 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 74  ven though SQLit
35c80 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74 61  e strives to sta
35c90 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c  y.** below the l
35ca0 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 78  imit, it will ex
35cb0 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20 72  ceed the limit r
35cc0 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65 72  ather than gener
35cd0 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54  ate.** an [SQLIT
35ce0 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20  E_NOMEM] error. 
35cf0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
35d00 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
35d10 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 69  imit .** is advi
35d20 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
35d30 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c   ^The return val
35d40 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
35d50 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
35d60 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65 20  4() is the size 
35d70 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68  of.** the soft h
35d80 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 20  eap limit prior 
35d90 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e 49  to the call.  ^I
35da0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e  f the argument N
35db0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
35dc0 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69  then no change i
35dd0 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73 6f  s made to the so
35de0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20  ft heap limit.  
35df0 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72 65  Hence, the curre
35e00 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68  nt.** size of th
35e10 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
35e20 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
35e30 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a  ned by invoking.
35e40 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  ** sqlite3_soft_
35e50 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 77  heap_limit64() w
35e60 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20 61  ith a negative a
35e70 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
35e80 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
35e90 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 74  N is zero then t
35ea0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
35eb0 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  it is disabled..
35ec0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74  **.** ^(The soft
35ed0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6e   heap limit is n
35ee0 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 74  ot enforced in t
35ef0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
35f00 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20  mentation.** if 
35f10 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66  one or more of f
35f20 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69  ollowing conditi
35f30 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a  ons are true:.**
35f40 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
35f50 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   The soft heap l
35f60 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 7a  imit is set to z
35f70 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d  ero..** <li> Mem
35f80 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
35f90 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  s disabled using
35fa0 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
35fb0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73  f the.**      [s
35fc0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
35fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
35fe0 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74  MSTATUS],...) st
35ff0 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  art-time option 
36000 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  and.**      the 
36010 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
36020 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 69  MEMSTATUS] compi
36030 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
36040 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72  ** <li> An alter
36050 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68  native page cach
36060 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
36070 20 69 73 20 73 70 65 63 69 66 69 65 64 20 75 73   is specified us
36080 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c  ing.**      [sql
36090 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
360a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
360b0 48 45 32 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c  HE2],...)..** <l
360c0 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68  i> The page cach
360d0 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d  e allocates from
360e0 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20   its own memory 
360f0 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a  pool supplied.**
36100 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
36110 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
36120 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
36130 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20  HE],...) rather 
36140 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f  than.**      fro
36150 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c  m the heap..** <
36160 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67  /ul>)^.**.** Beg
36170 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
36180 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33  te version 3.7.3
36190 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
361a0 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
361b0 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  d.** regardless 
361c0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
361d0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  t the [SQLITE_EN
361e0 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
361f0 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69  GEMENT].** compi
36200 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
36210 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68  s invoked.  With
36220 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
36230 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
36240 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20  T],.** the soft 
36250 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
36260 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20  forced on every 
36270 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
36280 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b  n.  Without.** [
36290 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
362a0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
362b0 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
362c0 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e  limit is only en
362d0 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d  forced.** when m
362e0 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
362f0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63  ed by the page c
36300 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73  ache.  Testing s
36310 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63  uggests that bec
36320 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65  ause.** the page
36330 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72   cache is the pr
36340 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79  edominate memory
36350 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c   user in SQLite,
36360 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
36370 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65  tions will achie
36380 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74  ve adequate soft
36390 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f   heap limit enfo
363a0 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a  rcement without.
363b0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53  ** the use of [S
363c0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
363d0 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
363e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75  .**.** The circu
363f0 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77  mstances under w
36400 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c  hich SQLite will
36410 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66   enforce the sof
36420 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79  t heap limit may
36430 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66  .** changes in f
36440 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
36450 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c  f SQLite..*/.sql
36460 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
36470 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
36480 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74  it64(sqlite3_int
36490 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  64 N);../*.** CA
364a0 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
364b0 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d  ed Soft Heap Lim
364c0 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20  it Interface.** 
364d0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
364e0 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65   This is a depre
364f0 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  cated version of
36500 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   the [sqlite3_so
36510 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
36520 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
36530 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69    This routine i
36540 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68  s provided for h
36550 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
36560 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e  ibility.** only.
36570 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63    All new applic
36580 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73  ations should us
36590 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
365a0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
365b0 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65  t64()] interface
365c0 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69   rather than thi
365d0 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  s one..*/.SQLITE
365e0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
365f0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
36600 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b  ap_limit(int N);
36610 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
36620 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  F: Extract Metad
36630 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
36640 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a  mn Of A Table.**
36650 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
36660 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
36670 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
36680 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
36690 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
366a0 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
366b0 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
366c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
366d0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
366e0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
366f0 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
36700 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
36710 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
36720 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
36730 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
36740 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
36750 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e  s to.** this fun
36760 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f  ction. ^The seco
36770 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
36780 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
36790 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
367a0 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
367b0 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61   "temp", or an a
367c0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
367d0 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
367e0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61   specified.** ta
367f0 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66  ble or NULL. ^If
36800 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
36810 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
36820 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
36830 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
36840 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
36850 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
36860 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61  used by the data
36870 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a  base engine to.*
36880 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
36890 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
368a0 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rences..**.** ^T
368b0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
368c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
368d0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
368e0 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
368f0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65  d column.** name
36900 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
36910 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
36920 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
36930 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
36940 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  s.** may be NULL
36950 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74  ..**.** ^Metadat
36960 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  a is returned by
36970 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
36980 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
36990 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35   passed as the 5
369a0 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71  th.** and subseq
369b0 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
369c0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
369d0 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20  . ^Any of these 
369e0 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
369f0 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69  .** NULL, in whi
36a00 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72  ch case the corr
36a10 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e  esponding elemen
36a20 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73  t of metadata is
36a30 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
36a40 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ^(<blockquote>.*
36a50 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
36a60 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
36a70 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20   Parameter <th> 
36a80 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c  Output<br>Type <
36a90 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e  th>  Description
36aa0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
36ab0 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  5th <td> const c
36ac0 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74  har* <td> Data t
36ad0 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ype.** <tr><td> 
36ae0 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  6th <td> const c
36af0 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f  har* <td> Name o
36b00 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  f default collat
36b10 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20  ion sequence.** 
36b20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64  <tr><td> 7th <td
36b30 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
36b40 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
36b50 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
36b60 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c   constraint.** <
36b70 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e  tr><td> 8th <td>
36b80 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
36b90 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
36ba0 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
36bb0 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c  PRIMARY KEY.** <
36bc0 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e  tr><td> 9th <td>
36bd0 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
36be0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
36bf0 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45   is [AUTOINCREME
36c00 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  NT].** </table>.
36c10 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
36c20 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  )^.**.** ^The me
36c30 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
36c40 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
36c50 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
36c60 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65  ed for the.** de
36c70 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
36c80 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
36c90 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
36ca0 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
36cb0 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  xt.** call to an
36cc0 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e  y SQLite API fun
36cd0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ction..**.** ^If
36ce0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74   the specified t
36cf0 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79  able is actually
36d00 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72   a view, an [err
36d10 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
36d20 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  rned..**.** ^If 
36d30 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
36d40 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
36d50 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
36d60 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49  d_" and an.** [I
36d70 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
36d80 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62  EY] column has b
36d90 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64  een explicitly d
36da0 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68  eclared, then th
36db0 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
36dc0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
36dd0 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
36de0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
36df0 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73  n. ^(If there is
36e00 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
36e10 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
36e20 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
36e30 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
36e40 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
36e50 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
36e60 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
36e70 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
36e80 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
36e90 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
36ea0 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
36eb0 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
36ec0 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
36ed0 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
36ee0 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
36ef0 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
36f00 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  e>)^.**.** ^(Thi
36f10 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
36f20 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
36f30 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
36f40 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
36f50 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
36f60 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
36f70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
36f80 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
36f90 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
36fa0 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
36fb0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
36fc0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
36fd0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
36fe0 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20   left.** in the 
36ff0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37000 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74  tion] (to be ret
37010 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
37020 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29  ite3_errmsg()).)
37030 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50  ^.**.** ^This AP
37040 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
37050 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
37060 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
37070 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
37080 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
37090 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
370a0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
370b0 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  l defined..*/.in
370c0 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  t sqlite3_table_
370d0 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
370e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
370f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
37100 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  * Connection han
37110 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
37120 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
37130 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
37140 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f   name or NULL */
37150 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37160 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f  TableName,     /
37170 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a  * Table name */.
37180 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
37190 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a  olumnName,    /*
371a0 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a   Column name */.
371b0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
371c0 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a  zDataType,    /*
371d0 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65   OUTPUT: Declare
371e0 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20  d data type */. 
371f0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
37200 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20  CollSeq,     /* 
37210 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f  OUTPUT: Collatio
37220 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  n sequence name 
37230 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75  */.  int *pNotNu
37240 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ll,             
37250 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
37260 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e   if NOT NULL con
37270 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a  straint exists *
37280 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72  /.  int *pPrimar
37290 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20  yKey,           
372a0 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
372b0 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f  if column part o
372c0 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  f PK */.  int *p
372d0 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20  Autoinc         
372e0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
372f0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
37300 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e  is auto-incremen
37310 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
37320 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e  API3REF: Load An
37330 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a   Extension.**.**
37340 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
37350 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65   loads an SQLite
37360 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
37370 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65  ry from the name
37380 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d file..**.** ^T
37390 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
373a0 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
373b0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
373c0 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c  o load an.** SQL
373d0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
373e0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
373f0 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c  in the file zFil
37400 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e  e..**.** ^The en
37410 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
37420 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61  oc..** ^zProc ma
37430 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68  y be 0, in which
37440 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
37450 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
37460 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f  t.** defaults to
37470 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
37480 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54  ion_init"..** ^T
37490 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
374a0 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
374b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
374c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
374d0 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
374e0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
374f0 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
37500 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  ng..** ^If an er
37510 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70  ror occurs and p
37520 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30  zErrMsg is not 0
37530 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73  , then the.** [s
37540 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
37550 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
37560 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74  ce shall attempt
37570 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45   to.** fill *pzE
37580 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72  rrMsg with error
37590 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74   message text st
375a0 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ored in memory.*
375b0 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
375c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
375d0 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  )]. The calling 
375e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  function.** shou
375f0 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
37600 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ory by calling [
37610 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
37620 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
37630 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
37640 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a  e enabled using.
37650 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ** [sqlite3_enab
37660 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
37670 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61  n()] prior to ca
37680 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a  lling this API,.
37690 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
376a0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
376b0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  turned..**.** Se
376c0 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64  e also the [load
376d0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c  _extension() SQL
376e0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69   function]..*/.i
376f0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
37700 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
37710 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
37720 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
37730 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
37740 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
37750 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
37760 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
37770 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
37780 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
37790 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
377a0 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
377b0 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
377c0 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
377d0 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
377e0 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
377f0 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
37800 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
37810 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
37820 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
37830 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
37840 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
37850 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
37860 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e  g.**.** ^So as n
37870 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72  ot to open secur
37880 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64  ity holes in old
37890 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  er applications 
378a0 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72  that are.** unpr
378b0 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77  epared to deal w
378c0 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  ith extension lo
378d0 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20  ading, and as a 
378e0 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69  means of disabli
378f0 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20  ng.** extension 
37900 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76  loading while ev
37910 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e  aluating user-en
37920 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66  tered SQL, the f
37930 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
37940 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74  is provided to t
37950 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
37960 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
37970 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20  )] mechanism on 
37980 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e  and off..**.** ^
37990 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
379a0 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
379b0 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20  ult. See ticket 
379c0 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20  #1863..** ^Call 
379d0 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  the sqlite3_enab
379e0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
379f0 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68  n() routine with
37a00 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20   onoff==1.** to 
37a10 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
37a20 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
37a30 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
37a40 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69  ==0 to turn.** i
37a50 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e  t back off again
37a60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37a70 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
37a80 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
37a90 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
37aa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37ab0 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
37ac0 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c  oad Statically L
37ad0 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73  inked Extensions
37ae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
37af0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
37b00 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  e xEntryPoint() 
37b10 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
37b20 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61  nvoked for.** ea
37b30 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ch new [database
37b40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
37b50 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  t is created.  T
37b60 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20  he idea here is 
37b70 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f  that.** xEntryPo
37b80 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74  int() is the ent
37b90 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73  ry point for a s
37ba0 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
37bb0 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
37bc0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20  n.** that is to 
37bd0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
37be0 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c   loaded into all
37bf0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
37c00 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  nnections..**.**
37c10 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74   ^(Even though t
37c20 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74  he function prot
37c30 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74  otype shows that
37c40 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74   xEntryPoint() t
37c50 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d  akes.** no argum
37c60 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73  ents and returns
37c70 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e   void, SQLite in
37c80 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e  vokes xEntryPoin
37c90 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a  t() with three.*
37ca0 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20  * arguments and 
37cb0 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65  expects and inte
37cc0 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66  ger result as if
37cd0 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f   the signature o
37ce0 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70  f the.** entry p
37cf0 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f  oint where as fo
37d00 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
37d10 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
37d20 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45  * &nbsp;  int xE
37d30 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e  ntryPoint(.** &n
37d40 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20  bsp;    sqlite3 
37d50 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  *db,.** &nbsp;  
37d60 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
37d70 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73  zErrMsg,.** &nbs
37d80 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75  p;    const stru
37d90 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
37da0 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a  outines *pThunk.
37db0 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a  ** &nbsp;  );.**
37dc0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
37dd0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20  ote>)^.**.** If 
37de0 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20  the xEntryPoint 
37df0 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65  routine encounte
37e00 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20  rs an error, it 
37e10 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45  should make *pzE
37e20 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74  rrMsg.** point t
37e30 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  o an appropriate
37e40 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28   error message (
37e50 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
37e60 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
37e70 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e  ]).** and return
37e80 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
37e90 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e  [error code].  ^
37ea0 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74  SQLite ensures t
37eb0 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a  hat *pzErrMsg.**
37ec0 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20   is NULL before 
37ed0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74  calling the xEnt
37ee0 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c  ryPoint().  ^SQL
37ef0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  ite will invoke.
37f00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
37f10 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67  ()] on *pzErrMsg
37f20 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69   after xEntryPoi
37f30 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e  nt() returns.  ^
37f40 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79  If any.** xEntry
37f50 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20  Point() returns 
37f60 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73  an error, the [s
37f70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
37f80 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
37f90 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
37fa0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61  e3_open_v2()] ca
37fb0 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64  ll that provoked
37fc0 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
37fd0 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a  () will fail..**
37fe0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
37ff0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
38000 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65  ion(X) with an e
38010 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61  ntry point X tha
38020 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20  t is already.** 
38030 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61  on the list of a
38040 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
38050 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ons is a harmles
38060 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74  s no-op. ^No ent
38070 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c  ry point.** will
38080 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20   be called more 
38090 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61  than once for ea
380a0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
380b0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f  ection that is o
380c0 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  pened..**.** See
380d0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
380e0 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
380f0 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sion()]..*/.int 
38100 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
38110 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45  ension(void (*xE
38120 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29  ntryPoint)(void)
38130 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38140 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
38150 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
38160 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ading.**.** ^Thi
38170 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 73 61  s interface disa
38180 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74  bles all automat
38190 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72  ic extensions pr
381a0 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69  eviously.** regi
381b0 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
381c0 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
381d0 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  sion()]..*/.void
381e0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
381f0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
38200 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  id);../*.** The 
38210 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
38220 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
38230 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72  echanism is curr
38240 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
38250 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
38260 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
38270 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
38280 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
38290 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
382a0 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
382b0 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
382c0 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
382d0 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
382e0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
382f0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
38300 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
38310 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
38320 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
38330 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
38340 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
38350 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
38360 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
38370 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75  /../*.** Structu
38380 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20  res used by the 
38390 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
383a0 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64  terface.*/.typed
383b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
383c0 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76  3_vtab sqlite3_v
383d0 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72  tab;.typedef str
383e0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
383f0 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69  x_info sqlite3_i
38400 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64  ndex_info;.typed
38410 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
38420 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71  3_vtab_cursor sq
38430 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
38440 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  r;.typedef struc
38450 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
38460 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b   sqlite3_module;
38470 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38480 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
38490 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
384a0 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
384b0 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  le {virtual tabl
384c0 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20  e module}.**.** 
384d0 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20  This structure, 
384e0 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64  sometimes called
384f0 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c   a "virtual tabl
38500 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64  e module", .** d
38510 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65  efines the imple
38520 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b  mentation of a [
38530 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
38540 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63    .** This struc
38550 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f  ture consists mo
38560 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
38570 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
38580 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c  **.** ^A virtual
38590 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73   table module is
385a0 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c   created by fill
385b0 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74  ing in a persist
385c0 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20  ent.** instance 
385d0 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
385e0 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
385f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
38600 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b  instance.** to [
38610 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
38620 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
38630 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
38640 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  le_v2()]..** ^Th
38650 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72  e registration r
38660 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74  emains valid unt
38670 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65  il it is replace
38680 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74  d by a different
38690 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e  .** module or un
386a0 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73  til the [databas
386b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c  e connection] cl
386c0 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65  oses.  The conte
386d0 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74  nt.** of this st
386e0 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74  ructure must not
386f0 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74   change while it
38700 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
38710 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62  ith.** any datab
38720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
38730 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
38740 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
38750 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
38760 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
38770 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
38780 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
38790 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
387a0 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
387b0 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
387c0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
387d0 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
387e0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
387f0 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
38800 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
38810 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
38820 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
38830 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
38840 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
38850 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
38860 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
38870 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
38880 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 5